Cancel an order - v3

curl --request POST \
  --url https://api.snappy.com/public-api/v3/orders/{orderId}/cancel \
  --header 'X-Api-Key: <api-key>'

{
  "data": {
    "id": "G7nR4bD9mK",
    "createdAt": "2026-05-27T10:30:00.000Z",
    "status": "active",
    "fulfillmentStatus": "unfulfilled",
    "tags": [],
    "cancellationDetails": {
      "cancelledAt": "2026-05-27T15:57:00.000Z",
      "cancellationReason": "customer_requested"
    },
    "lineItems": [
      {
        "variantId": "v_abc12345",
        "quantity": 1,
        "title": "Premium Gift Card"
      }
    ],
    "fulfillments": [
      {
        "fulfillmentLineItems": [
          {
            "variantId": "v_abc12345",
            "quantity": 1,
            "title": "Premium Gift Card"
          }
        ],
        "id": "tr_abc123",
        "status": "inTransit",
        "trackingCompany": "UPS",
        "trackingInfo": {
          "number": "1Z9999W99999999999",
          "url": "https://www.ups.com/track?tracknum=1Z9999W99999999999"
        }
      }
    ],
    "recipient": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+15555555555"
    },
    "shippingAddress": {
      "address1": "123 Main St",
      "address2": "Suite A",
      "city": "New York",
      "provinceCode": "NY",
      "countryCode": "US",
      "postalCode": "10001"
    },
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "idempotencyKey": "order-2026-05-13-abc"
  }
}

Orders

Cancel order

Use this endpoint to cancel an order that has not yet been picked up by the fulfillment partner. Use this when the recipient or sender requests a cancellation before the shipment is in transit.

Required fields:

orderId - the order identifier, passed as a path parameter.

Optional parameters:

Snappy-Account-Id header - optional account scoping.
Snappy-Company-Id header - optional company scoping.

Behavior Notes:

On success, returns the full Order object with status: "cancelled", fulfillmentStatus: "cancelled", and a populated cancellationDetails object containing cancelledAt and cancellationReason.
cancellationReason is currently hardcoded to “customer_requested”. Caller-supplied reasons may be added in a future release.
cancellationReason is currently hardcoded to customer_requested. Caller-supplied reasons may be added in a future release.
Returns 404 if no order exists for the supplied orderId, or if it exists but belongs to a different Company. Existence is intentionally hidden across Companies.
Returns 422 when the order cannot be cancelled - typically because it is already in transit, already delivered, or already cancelled. The error envelope identifies which case fired.
Cancellation is terminal. A cancelled order cannot be re-activated; if the recipient still needs a gift, place a new order via POST /v3/orders.

Permissions

Requires: orders:cancel

POST

orders

{orderId}

cancel

Cancel an order - v3

curl --request POST \
  --url https://api.snappy.com/public-api/v3/orders/{orderId}/cancel \
  --header 'X-Api-Key: <api-key>'

{
  "data": {
    "id": "G7nR4bD9mK",
    "createdAt": "2026-05-27T10:30:00.000Z",
    "status": "active",
    "fulfillmentStatus": "unfulfilled",
    "tags": [],
    "cancellationDetails": {
      "cancelledAt": "2026-05-27T15:57:00.000Z",
      "cancellationReason": "customer_requested"
    },
    "lineItems": [
      {
        "variantId": "v_abc12345",
        "quantity": 1,
        "title": "Premium Gift Card"
      }
    ],
    "fulfillments": [
      {
        "fulfillmentLineItems": [
          {
            "variantId": "v_abc12345",
            "quantity": 1,
            "title": "Premium Gift Card"
          }
        ],
        "id": "tr_abc123",
        "status": "inTransit",
        "trackingCompany": "UPS",
        "trackingInfo": {
          "number": "1Z9999W99999999999",
          "url": "https://www.ups.com/track?tracknum=1Z9999W99999999999"
        }
      }
    ],
    "recipient": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+15555555555"
    },
    "shippingAddress": {
      "address1": "123 Main St",
      "address2": "Suite A",
      "city": "New York",
      "provinceCode": "NY",
      "countryCode": "US",
      "postalCode": "10001"
    },
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "idempotencyKey": "order-2026-05-13-abc"
  }
}

Authorizations

X-Api-Key

string

header

required

Company Level Authentication

Include your API key in the X-Api-Key header for every request:

X-Api-Key: YOUR_API_KEY

Headers

snappy-account-id

string

Optional account identifier for swag validation/filtering.

Example:

"acc123456"

snappy-company-id

string

Optional company identifier for swag validation/filtering.

Example:

"cmp123456"

Path Parameters

orderId

string

required

The unique identifier of the order to cancel. Obtained from POST /v3/orders or GET /v3/orders.

Pattern: ^[A-Za-z0-9]{8,}$

Example:

"G7nR4bD9mK"

Response

Cancelled order.

JSON:API single-resource envelope for an order.

data

object

required

Order details including line items, recipient, shipping address, fulfillments, and tracking information.

Show child attributes

Last modified on June 17, 2026

Get order by ID

Validate order address