Subscribe Pro HTTP Order Callback

The Subscribe Pro Order Callback is one method Subscribe Pro offers to create recurring orders in your existing e-commerce 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 send 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 e-commerce platform order order management system).

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

    Your handler must return an HTTP status code of 201, 202 or 409, indicating that the order was successfully received and whether all, some, or none of the items were successfully ordered. The response should be sent with a Content-Type of 'application/json' and conform to the following schema for Order Callback Response.

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: