FOfourthwall
External Orders

Create external order

Changed on

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

  • Base URL
    https://api.fourthwall.com
  • URL
    https://api.fourthwall.com/open-api/v1.0/external-orders
  • Auth
    • OAuth 2
      Implicit: https://auth.staging.fourthwall.com/auth/realms/Fourthwall/protocol/openid-connect/auth
      Scopes: order_write
    • or HTTP basic

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"
    }
  }
}

Changes

  • d02dd5a76313Revision changes
    • warning

      removed the request property //

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the non-success response with the status