Update Order

Updates an order. You can change the recipient, the payment method, and the locale. To change payment, send the full object. Change it to set payerAddress when the payment status is requires-crypto-payer-address, or receiptEmail when it is requires-email.

API scope required: orders.update

PATCH /2022-06-09/orders/{orderId}

cURL

Change Recipient

curl --request PATCH \
  --url https://staging.crossmint.com/api/2022-06-09/orders/{orderId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "recipient": {
    "walletAddress": "0x5b1f2e8a9c3d4e7f6a0b1c2d3e4f5a6b7c8d9e0f"
  }
}
'

200

{
  "lineItems": [
    {
      "chain": "base",
      "delivery": {
        "status": "failed",
        "completedAt": "2024-01-15T10:30:00.000Z",
        "failureReason": {
          "code": "transfer-failed",
          "message": "The delivery transaction reverted on chain."
        },
        "rail": "ach-us",
        "recipient": {
          "email": "[e-mail]",
          "locator": "email:[e-mail]:base",
          "walletAddress": "0x9fDA6b2C3e4d5e6F7a8B9c0D1e2F3a4B5c6D7e8F",
          "physicalAddress": {
            "city": "San Francisco",
            "country": "US",
            "line1": "123 Market St",
            "name": "Jane Doe",
            "postalCode": "94105",
            "line2": "Apt 4B",
            "state": "CA",
            "stateOrRegion": "CA"
          }
        }
      },
      "executionMode": "exact-in",
      "maxSlippageBps": "500",
      "metadata": {
        "description": "USDC Token",
        "imageUrl": "https://cryptologos.cc/logos/usd-coin-usdc-logo.svg",
        "name": "USDC",
        "collection": {
          "description": "Stablecoin issued by Circle, pegged 1:1 to the US dollar.",
          "imageUrl": "https://cryptologos.cc/logos/usd-coin-usdc-logo.svg",
          "name": "USD Coin"
        }
      },
      "quote": {
        "quantityRange": {
          "lowerBound": "9.95",
          "upperBound": "10.00"
        },
        "status": "valid",
        "charges": {
          "unit": {
            "amount": "1.00",
            "currency": "usd"
          },
          "crossmintFees": {
            "amount": "0.37",
            "currency": "usd"
          },
          "fees": {
            "amount": "0.47",
            "currency": "usd",
            "type": "exact"
          },
          "gas": {
            "amount": "0.10",
            "currency": "usd"
          },
          "networkFee": {
            "amount": "0.10",
            "currency": "usd"
          },
          "salesTax": {
            "amount": "0.84",
            "currency": "usd"
          },
          "shipping": {
            "amount": "4.99",
            "currency": "usd"
          },
          "transferFee": {
            "amount": "0.50",
            "currency": "usdc"
          }
        },
        "totalPrice": {
          "amount": "10.47",
          "currency": "usd"
        },
        "unavailabilityReason": {
          "code": "to",
          "message": "This item is sold out."
        }
      },
      "callData": {},
      "executionParams": {
        "amount": "10.47",
        "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "maxSlippageBps": "500",
        "mode": "exact-in"
      }
    }
  ],
  "locale": "en-US",
  "orderId": "b2959ca5-65e4-466a-bd26-1bd05cb4f837",
  "payment": {
    "currency": "usd",
    "method": "stripe-payment-element",
    "status": "awaiting-payment",
    "failureReason": {
      "code": "issuer_decline",
      "category": "authorization_decline",
      "developerMessage": "Generic issuer decline (do_not_honor). Do not retry automatically; ask the buyer to contact their bank.",
      "message": "Payment declined by your bank. Contact your bank or try a different payment method.",
      "retryPolicy": "contact_payment_provider"
    },
    "payer": {
      "deviceId": "8f3a1c2b9d4e5f60718293a4b5c6d7e8",
      "paymentMethodId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
    },
    "preparation": {
      "chain": "base",
      "payerAddress": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "serializedTransaction": "0x02f8b0…",
      "transactionParameters": {
        "amount": "10470000",
        "memo": "b2959ca5-65e4-466a-bd26-1bd05cb4f837"
      }
    },
    "receiptEmail": "[e-mail]",
    "received": {
      "amount": "10.47",
      "chain": "base",
      "currency": "usd",
      "txId": "0x33be4e2d636a22b56cb28b858f682dd428c7f468367072e2711c09cdd42cf826"
    },
    "refunded": {
      "amount": "10.47",
      "chain": "base",
      "currency": "usd",
      "txId": "0x7c0a4f9e2b1d8c3a6e5f4b2d1c0a9e8f7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d"
    }
  },
  "phase": "payment",
  "quote": {
    "status": "valid",
    "exchangeRate": {
      "destinationCurrency": "mxn",
      "rate": "17.4523",
      "sourceCurrency": "usdc"
    },
    "expiresAt": "2024-01-15T10:30:00.000Z",
    "quotedAt": "2024-01-15T10:30:00.000Z",
    "totalPrice": {
      "amount": "10.47",
      "currency": "usd"
    }
  },
  "legal": {
    "requirements": [
      {
        "display": "show-checkbox",
        "type": "crossmint-terms-of-service",
        "url": "https://www.crossmint.com/legal/terms-of-service"
      }
    ],
    "shownBy": "crossmint"
  },
  "metadata": {
    "internalOrderId": "ORD-10042"
  }
}

Authorizations

apiKeyorderClientSecret

X-API-KEY · string · header · required

API key required for authentication

Path Parameters

orderId · string · required

The order ID, in UUID format. Create Order returns it as order.orderId.

Example:

"9c82ef99-617f-497d-9abb-fd355291681b"

Body

application/json

Fields to change on the order. Send only the fields that change.

locale · enum<string>

Locale for the checkout, in IETF BCP 47. It impacts the email receipt language. Ensure your UI is set to the same language as specified here. Throws an error if passed an invalid language.

Available options: Klingon, de-DE, en-US, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-PT, ru-RU, th-TH, tr-TR, uk-UA, vi-VN, zh-CN, zh-TW

payment · Bank transfer (EUR) · object

How the buyer pays. method selects a card provider, a bank transfer, a prefunded balance, or the chain that the crypto payment is sent from. currency is the currency that the buyer pays in.

Bank transfer (EUR)

Wirex prefunded balance (EUR)

Card (tokenized)

Card

Card token

Card via Checkout.com Flow

Card via Stripe Payment Element

Solana

EVM

Sui

Show child attributes

recipient · Email · object

Who receives the items. Send one of email, walletAddress, or paymentMethodId. If you send an email, Crossmint creates a custodial wallet for it. If you send no recipient, the order quote has the status requires-recipient until you set one with Update Order.

Email

Payment method

Wallet address

Show child attributes

Response

200

application/json

Order updated successfully.

lineItems · (Exact-in (fixed spend) · object | Exact-out (fixed quantity) · object)[] · required

Items in the order. Each line item has its own quote and delivery status.

Exact-in (fixed spend)

Exact-out (fixed quantity)

Show child attributes

locale · enum<string> · required

Locale for the checkout, in IETF BCP 47. It impacts the email receipt language. Ensure your UI is set to the same language as specified here. Throws an error if passed an invalid language.

Available options: Klingon, de-DE, en-US, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-PT, ru-RU, th-TH, tr-TR, uk-UA, vi-VN, zh-CN, zh-TW

Example:

"en-US"

orderId · string<uuid> · required

Unique ID of the order, in UUID format.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Example:

"b2959ca5-65e4-466a-bd26-1bd05cb4f837"

payment · object · required

Payment leg of the order. Read status to find the next action.

Show child attributes

phase · enum<string> · required

Current phase of the order lifecycle. quote: the quote is not final. payment: the order waits for the payment. delivery: the payment is received and delivery is in progress. completed: every line item is delivered.

Available options: completed, delivery, payment, quote

Example:

"payment"

quote · object · required

Quote for the whole order. Its values aggregate the line item quotes.

Show child attributes

legal · object

Terms that apply to the order. Absent from List Orders responses.

Show child attributes

metadata · object

Metadata that you sent when you created the order.

Show child attributes

Example:

{ "internalOrderId": "ORD-10042" }