---
title: "Set or revert fulfillment dates"
description: "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."
---

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

`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](/contracts/effective-dates); you only need this endpoint if your platform is not one SureBright already listens to.

## Headers

| Header | Description | Required |
|--------|-------------|----------|
| Authorization | `Bearer` 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-Type | `application/json` | Yes |

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

## Request body

<ParamField body="contractIds" type="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.
</ParamField>

<ParamField body="action" type="string" default="SET">
  `SET` stamps the coverage dates from `fulfillmentDate`. `REVERT` clears them. Case-insensitive; any other value is rejected.
</ParamField>

<ParamField body="fulfillmentDate" type="string">
  The shipment date and time, ISO 8601 (for example `2026-11-05T14:32:00Z`). Required for `SET`, ignored for `REVERT`.
</ParamField>

<ParamField body="reason" type="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.
</ParamField>

## 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.

<ResponseField name="isError" type="boolean">
  `true` when any entry in `results` has `isError: true`.
</ResponseField>

<ResponseField name="message" type="string">
  `Fulfillment dates updated`, `Fulfillment dates reverted`, `One or more contracts failed to update` or `One or more contracts failed to revert`.
</ResponseField>

<ResponseField name="results" type="object[]">
  One entry per contract in `contractIds`, in the same order.
  <Expandable title="SET result">
    <ResponseField name="contractId" type="string">The contract this entry is about.</ResponseField>
    <ResponseField name="isError" type="boolean">`true` when the contract was not dated.</ResponseField>
    <ResponseField name="skipped" type="boolean">Present and `true` when the contract already had dates.</ResponseField>
    <ResponseField name="message" type="string">Set on skipped and failed entries, for example `Dates already set — skipped (first fulfillment wins)`, `Contract not found` or `Version conflict — not dated after 3 attempt(s)`.</ResponseField>
    <ResponseField name="effectiveDate" type="string">Coverage start, `MM/DD/YYYY`.</ResponseField>
    <ResponseField name="expirationDate" type="string">Coverage end, `MM/DD/YYYY`.</ResponseField>
    <ResponseField name="isFixPending" type="boolean">Whether the contract still has something to resolve. See [Why a contract is on hold](/contracts/holds).</ResponseField>
    <ResponseField name="holdReasonList" type="string[]">The holds left on the contract after dating.</ResponseField>
  </Expandable>
  <Expandable title="REVERT result">
    <ResponseField name="contractId" type="string">The contract this entry is about.</ResponseField>
    <ResponseField name="isError" type="boolean">`true` when the dates could not be cleared.</ResponseField>
    <ResponseField name="reverted" type="boolean">`true` when the dates were cleared.</ResponseField>
    <ResponseField name="skipped" type="boolean">Present and `true` when there was nothing to revert.</ResponseField>
    <ResponseField name="message" type="string">On skipped entries: `Contract is cancelled — nothing to revert` or `No fulfillment dates set — already awaiting fulfillment`.</ResponseField>
    <ResponseField name="reason" type="string">The `reason` you sent, if any.</ResponseField>
    <ResponseField name="isFixPending" type="boolean">Whether the contract has something to resolve.</ResponseField>
    <ResponseField name="holdReasonList" type="string[]">The holds on the contract after the revert; includes `AWAITING_FULFILLMENT`.</ResponseField>
    <ResponseField name="lifecycleState" type="string">The contract's lifecycle state. See [Contract statuses](/contracts/lifecycle).</ResponseField>
    <ResponseField name="paymentState" type="string">The contract's payment state.</ResponseField>
  </Expandable>
</ResponseField>

```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

| Status | Body | Cause |
|--------|------|-------|
| `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.
