Order Callback - Building The Response


The response you return from your order callback handler should include an order number, details about the order which was placed (if any) and / or error details about subscription items which failed to be ordered, potentially including Subscribe Pro error class. The HTTP status should indicate the result.

Success Response - HTTP Status 201

Return a response similar to the following when all subscription items were handled successfully and an e-commerce order was successfully placed. See here for detailed documentation of the order details schema.

{
  "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",
      }
    ]
  },
  "errorItems": []
}

Partial Success Response - HTTP Status 202

Return a response similar to the following when some subscription items were handled successfully, some items failed and an e-commerce order was successfully placed. See here for detailed documentation of the order details schema.

{
  "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",
      }
    ]
  },
  "itemErrors": [
      {
        "subscriptionId": "62343421",
        "errorMessage": "Product out of stock",
        "errorClass": "out_of_stock"
      }
  ]
}

All Items Failed Response - HTTP Status 409

Return a response similar to the following when all subscription items failed and no order was placed.

{
  "orderNumber": null,
  "orderDetails": null,
  "itemErrors": [
    {
      "subscriptionId": "413245234",
      "errorMessage": "Invalid product SKU",
      "errorClass": "product_config"
    },
    {
      "subscriptionId": "62343421",
      "errorMessage": "Product out of stock",
      "errorClass": "out_of_stock"
    }
  ]
}

Error Class Codes

The following error class codes, which you should include in the itemErrors[n].errorClass field, are used by Subscribe Pro to determine how to handle errors returned from the order callback.

See detailed retry behavior for each error class here: Automatic Ordering

Error Class CodeError ClassDescription
technologyTechnologyA technical error occurred, such as a network timeout or database error.
ecommerce_platformE-commerce Platform ErrorAn error occurred in the e-commerce platform, such as an invalid product SKU or out of stock product.
payment_cardPayment Card ErrorAn error occurred with the payment card, such as an expired card or invalid card number.
soft_declineSoft DeclineA soft decline occurred, such as an invalid address or invalid CVV.
hard_declineHard DeclineA hard decline occurred, such as insufficient funds or card expired.
expired_cardExpired CardThe payment card has expired.
out_of_stockOut of StockThe product is out of stock.
product_configProduct Configuration ErrorThe product configuration is invalid.