Set or revert fulfillment dates

Open a contract's coverage window when the product ships, or take it back when the shipment is cancelled, on stores where coverage starts at fulfillment.

Server-to-server endpoint. SureBright's Shopify and BigCommerce integrations call it for you; direct integrations are enabled per store by SureBright.

POST https://{HOST_NAME}/order/api/v1/contract/fulfillment

On a fulfillment-based store a contract is created with blank effective and expiration dates and held with AWAITING_FULFILLMENT until the product ships. This endpoint is the step that dates the contract (SET) or clears the dates again after a cancelled shipment (REVERT). The rules that turn a shipment date into coverage dates are described in When coverage starts; you only need this endpoint if your platform is not one SureBright already listens to.

Headers#

HeaderDescriptionRequired
AuthorizationBearer followed by the server-to-server token SureBright issues for your integration. This is not the merchant API key (sb_live_...) and it is not read from X-SureBright-Access-Token.Yes
Content-Typeapplication/jsonYes

A missing or malformed token returns 401 {"message": "Unauthorized"}.

Request body#

string[]required

The SureBright contract IDs to date or revert. Send the contracts for the units that shipped (or whose shipment was cancelled). Contracts that are already dated are reported as skipped, so it is safe to resend contracts from an earlier shipment.

stringdefault: SET

SET stamps the coverage dates from fulfillmentDate. REVERT clears them. Case-insensitive; any other value is rejected.

string

The shipment date and time, ISO 8601 (for example 2026-11-05T14:32:00Z). Required for SET, ignored for REVERT.

string

Optional free text for REVERT (for example the platform's cancellation reason). It is echoed back in the result and stored with the review case.

What SET does#

For each contract:

  1. If the contract already has a fulfillment or effective date it is left alone and reported with skipped: true. First fulfillment wins; a later shipment never re-dates a contract.

  2. Otherwise the effective date is computed from fulfillmentDate using the store's dating rules, the expiration date is the effective date plus the plan term, and the shipment date is stored as the contract's fulfillment date.

  3. The AWAITING_FULFILLMENT hold clears and, if the customer's confirmation email was deferred at order time, it is sent now.

What REVERT does#

For each contract that has dates:

  1. The effective, expiration and fulfillment dates are cleared, exactly as they were before the product shipped.

  2. The contract returns to the AWAITING_FULFILLMENT hold. It is not cancelled; a cancelled shipment is usually a re-ship, and the next SET dates it again.

  3. SureBright opens a review case for the contract so the cancelled shipment can be checked.

Contracts that are already cancelled, or that have no dates to take back, are reported with skipped: true and are not changed.

Example#

bash
curl -X POST https://{HOST_NAME}/order/api/v1/contract/fulfillment \
  -H 'Authorization: Bearer {SERVICE_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "contractIds": ["SB-7F3A9C21", "SB-7F3A9C22"],
    "action": "SET",
    "fulfillmentDate": "2026-11-05T14:32:00Z"
  }'
bash
curl -X POST https://{HOST_NAME}/order/api/v1/contract/fulfillment \
  -H 'Authorization: Bearer {SERVICE_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "contractIds": ["SB-7F3A9C21"],
    "action": "REVERT",
    "reason": "Shipment cancelled by carrier"
  }'

Response#

The call is processed contract by contract. It returns 200 when every contract succeeded or was skipped, and 500 with the same body shape when at least one contract failed. Check results[] either way.

isErrorboolean

true when any entry in results has isError: true.

messagestring

Fulfillment dates updated, Fulfillment dates reverted, One or more contracts failed to update or One or more contracts failed to revert.

resultsobject[]

One entry per contract in contractIds, in the same order.

json
{
  "isError": false,
  "message": "Fulfillment dates updated",
  "results": [
    {
      "contractId": "SB-7F3A9C21",
      "isError": false,
      "effectiveDate": "11/05/2026",
      "expirationDate": "11/05/2028",
      "isFixPending": false,
      "holdReasonList": []
    },
    {
      "contractId": "SB-7F3A9C22",
      "isError": false,
      "skipped": true,
      "message": "Dates already set — skipped (first fulfillment wins)",
      "effectiveDate": "10/28/2026",
      "expirationDate": "10/28/2028"
    }
  ]
}

Errors#

StatusBodyCause
400{"isError": true, "message": "contractIds is required"}contractIds missing or empty
400{"isError": true, "message": "action, when provided, must be one of: SET, REVERT"}Unknown action
400{"isError": true, "message": "fulfillmentDate is required"}SET without a date
401{"message": "Unauthorized"}Bearer token missing or not recognised
500{"isError": true, "message": "One or more contracts failed to update", "results": [...]}At least one contract was not found or lost a concurrent write after three attempts; resend those contract IDs
500{"isError": true, "message": "Internal Server Error"}Unexpected failure

A contract that fails with a version conflict was being written by another process at the same moment (for example a payment capture). Retrying the same request is safe: contracts that were dated in the meantime come back as skipped.