Sign in

v2

latestOpenAPI 3.1.02026-07-26102336742.6 KB
External Orders

Create external order

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Create an externally-paid order for fulfillment. This creates an order where payment was processed on an external marketplace (e.g., Etsy, Amazon) and Fourthwall handles fulfillment. The creator will be charged for fulfillment costs.

post/open-api/v1.0/external-orders

Request body

externalOrderIdstring required
externalSourcestring required
customerEmailstring
metadataobject
taxOverride'COLLECT' | 'SKIP'

Admin-only tax treatment override. COLLECT forces tax collection; SKIP forces no tax. Omit to use the default merchant-of-record rules. Honored only for internal Fourthwall admins; any other caller that sets it is rejected.

taxOverrideReasonstring

Justification for the override. Required when taxOverride = SKIP.

Example request

{
  "externalOrderId": "ETSY-123456789",
  "externalSource": "ETSY",
  "items": [
    {
      "variantId": "c2b6d0e3-4f5g-6h7i-8j9k-0l1m2n3o4p5q",
      "quantity": 2,
      "externalLineItemId": "etsy-line-item-123"
    }
  ],
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US",
    "phone": "+1-555-123-4567"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US",
    "phone": "+1-555-123-4567"
  },
  "customerEmail": "customer@example.com",
  "taxOverride": "SKIP",
  "taxOverrideReason": "Customer is the merchant of record (resale)"
}

Response

Created

orderIdstring uuid required
externalOrderIdstring required
externalSourcestring required
friendlyIdstring required
statusstring required
createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "orderId": "b1a5c9d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "externalOrderId": "ETSY-123456789",
  "externalSource": "ETSY",
  "friendlyId": "T4YTE8HA",
  "status": "CONFIRMED",
  "items": [
    {
      "quantity": 2,
      "externalLineItemId": "etsy-line-item-123",
      "unitCost": {
        "value": 10,
        "currency": "USD"
      },
      "totalCost": {
        "value": 10,
        "currency": "USD"
      },
      "itemFulfillmentFee": {
        "value": 10,
        "currency": "USD"
      },
      "itemShippingCost": {
        "value": 10,
        "currency": "USD"
      },
      "itemTotalCreatorCost": {
        "value": 10,
        "currency": "USD"
      }
    }
  ],
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US",
    "phone": "+1-555-123-4567"
  },
  "costs": {
    "fulfillmentFee": {
      "value": 10,
      "currency": "USD"
    },
    "manufacturingCost": {
      "value": 10,
      "currency": "USD"
    },
    "shippingCost": {
      "value": 10,
      "currency": "USD"
    },
    "totalCreatorCost": {
      "value": 10,
      "currency": "USD"
    }
  }
}