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.
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#
A missing or malformed token returns 401 {"message": "Unauthorized"}.
Request body#
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.
SETSET stamps the coverage dates from fulfillmentDate. REVERT clears them. Case-insensitive; any other value is rejected.
The shipment date and time, ISO 8601 (for example 2026-11-05T14:32:00Z). Required for SET, ignored for REVERT.
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:
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.Otherwise the effective date is computed from
fulfillmentDateusing 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.The
AWAITING_FULFILLMENThold 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:
The effective, expiration and fulfillment dates are cleared, exactly as they were before the product shipped.
The contract returns to the
AWAITING_FULFILLMENThold. It is not cancelled; a cancelled shipment is usually a re-ship, and the nextSETdates it again.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#
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"
}'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.
isErrorbooleantrue when any entry in results has isError: true.
messagestringFulfillment 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.
{
"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#
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.