Subscribe Pro HTTP Order Callback


The Subscribe Pro Order Callback is one method Subscribe Pro offers to create recurring orders in your existing eCommerce platform or order management system.

The Subscribe Pro platform's scheduling and automation engine is responsible to decide when its time to create a recurring order and what should be it's contents. When an HTTP order callback is configured, Subscribe Pro will make a synchronous HTTP request to the URL you have configured with the full details about the order to be created. Your callback handler is responsible to create the order and return details about the order which was created, such as the order number.

HTTP Order Callback Architecture

Order Callback Workflow

  1. Subscribe Pro sends a HTTP POST request to the web server where you have implemented a callback handler. The request will use a Content-Type of 'application/json' and contain all the necessary details about the order which should be created.

    See here for detailed documentation of the Callback Request Schema.

  2. To secure your order callback endpoint, your handler must validate that the request has come from Subscribe Pro. There are a few different approaches to handle this.

    See the Callback Security section for more detail about the following options:

    • Only allow Subscribe Pro servers to sent the request by whitelisting the Subscribe Pro IP addresses
    • Validate the HMAC signature on the request using the shared secret key provided by Subscribe Pro.

  3. Your handler is responsible to create or enter the order in your system (typically and eCommerce platform order order management system).

  4. Your handler should return a response which includes details about the order which was created, including vales such as orderNumber for the entire order and platformOrderItemId for each item.

    Your handler must return an HTTP status code between 200 and 299, indicating that the order was successfully received and created. The response should be sent with a Content-Type of 'application/json' and conform to the following schema for Order Details.

Example Request

Subscribe Pro will issue JSON requests similar to the following example:

{
  "customerId": "1234",
  "customerEmail": "[email protected]",
  "platformCustomerId": "1234",
  "salesOrderToken": "89adsfjkl129834kljsad98fuoi123uj489u23894",
  "currency": "USD",
  ...
  "payment": {
    "paymentToken": "8kj123489-afj123j4h-asdf",
    ...
  },
  "billingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    ...
  },
  "shippingAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    ...
  },
  "items": [
    {
      "productSku": "RUBY-RED",
      "shortDescription": "Ruby Red Black Tea - 2 oz.",
      "qty": "4",
      "requiresShipping": true,
      "subscription": {
        "id": "413245234"
      }
    }
  ]
}

Example Response

In your response, you should provide order number and order details. The following is an example which corresponds to the above request example:

{
  "orderNumber": "ABC-091293923",
  "orderDetails": {
    "customerId": "1234",
    "customerEmail": "[email protected]",
    "platformCustomerId": "1234",
    "platformOrderId": "091293923",
    "orderNumber": "ABC-091293923",
    "salesOrderToken": "89adsfjkl129834kljsad98fuoi123uj489u23894",
    "orderStatus": "placed",
    "orderState": "open",
    "orderDateTime": "2021-04-01T17:43:00Z",
    "currency": "USD",
    "shippingTotal": "7.2000",
    "taxTotal": "4.0000",
    "total": "51.2000",
    "billingAddress": {
      "firstName": "Jane",
      "lastName": "Doe",
      ...
    },
    "shippingAddress": {
      "firstName": "Jane",
      "lastName": "Doe",
      ...
    },
    "items": [
      {
        "platformOrderItemId": "735641231234",
        "productSku": "RUBY-RED",
        "productName": "Ruby Red Black Tea",
        "shortDescription": "Ruby Red Black Tea - 2 oz.",
        "qty": "4",
        "requiresShipping": true,
        "unitPrice": "10.0000",
        "shippingTotal": "7.2000",
        "taxTotal": "4.0000",
        "lineTotal": "51.2000",
        "subscriptionId": "413245234",
      }
    ]
  }
}

Request Schema

See here for detailed documentation of the callback request schema.

Security

All callback requests received from Subscribe Pro should be validated using the steps documented here: