> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fourthwall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create External Order

> *Rate limit: 100 requests / 10 seconds per shop. See [Rate limiting](/guides/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.

> [!WARNING]
>
> This endpoint is in beta and subject to change.

> [!NOTE]
>
> **OAuth scope:** `order_write`
>
> API keys have full access to this endpoint.


## OpenAPI

````yaml POST /open-api/v1.0/external-orders
openapi: 3.1.0
info:
  title: Fourthwall APIs
  description: Service used for management of orders, carts, and payments.
  termsOfService: https://fourthwall.com/terms-of-service
  contact:
    name: Backend team
    url: https://fourthwall.com
    email: backend@fourthwall.com
  version: unspecified
servers:
  - url: https://api.fourthwall.com
    description: Production server
security: []
externalDocs:
  description: OpenAPI documentation
  url: https://docs.fourthwall.com
paths:
  /open-api/v1.0/external-orders:
    post:
      tags:
        - External Orders
      summary: Create external order
      description: >-
        *Rate limit: 100 requests / 10 seconds per shop. See [Rate
        limiting](/guides/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.
      operationId: create-external-order
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/com.fourthwall.openapi.model.CreateExternalOrderRequest
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/com.fourthwall.openapi.model.ExternalOrderV1
        '400':
          description: >-
            Possible errors: `CHECKOUT_ITEMS_UNAVAILABLE_ERROR`,
            `CHECKOUT_OFFER_COST_NOT_SET_ERROR`,
            `CHECKOUT_PROMOTION_ALREADY_USED_BY_CUSTOMER`,
            `CHECKOUT_PROMOTION_AVAILABLE_ONLY_FOR_SIGNED_CUSTOMERS`,
            `CHECKOUT_PROMOTION_DOES_NOT_EXISTS`,
            `CHECKOUT_PROMOTION_FREE_SHIPPING_COUNTRY_NOT_SUPPORTED`,
            `CHECKOUT_PROMOTION_MAXIMUM_USES_LIMIT_EXCEEDED`,
            `CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TIER`,
            `CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TWITCH_TIER`,
            `CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_GIVEN_ITEMS`,
            `CHECKOUT_STOCK_NOT_ENOUGH_QUANTITY`,
            `EXTERNAL_ORDER_COUNTRY_NOT_SUPPORTED`,
            `EXTERNAL_ORDER_VALIDATION_FAILED`,
            `EXTERNAL_ORDER_VARIANT_NOT_FOUND`, `GIFT_NOT_FOUND`,
            `MESSAGE_VALIDATION_ERROR`, `ORDER_ITEMS_NO_LONGER_IN_STOCK_ERROR`,
            `PAYMENT_FREE_UNAVAILABLE_NON_ZERO`, `PAYMENT_PAYPAL_AUTH_ERROR`,
            `PAYMENT_PAYPAL_ORDER_NOT_APPROVED`, `PAYMENT_PAYPAL_UNKNOWN_ERROR`,
            `PAYMENT_PROVIDER_NOT_SUPPORTED`,
            `PAYMENT_UNPROCESSABLE_PAYPAL_ERROR`,
            `PROMOTION_ALREADY_USED_BY_CUSTOMER`,
            `PROMOTION_AVAILABLE_ONLY_FOR_SIGNED_CUSTOMERS`,
            `PROMOTION_FREE_SHIPPING_COUNTRY_NOT_SUPPORTED`,
            `PROMOTION_MAXIMUM_USES_LIMIT_EXCEEDED`,
            `PROMOTION_MISSING_REQUIRED_PRODUCTS`,
            `PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TIER`,
            `PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TWITCH_TIER`,
            `PROMOTION_NOT_ALLOWED_FOR_GIVEN_ITEMS`, `SHIPPING_RATES_ERROR`,
            `UNSUPPORTED_OPERATION_FOR_MANUFACTURER`,
            `VARIANT_NOT_ALLOWED_FOR_FREE_PRODUCTS`
          content:
            application/json:
              examples:
                checkout-items-unavailable-error:
                  value:
                    code: CHECKOUT_ITEMS_UNAVAILABLE_ERROR
                    unavailableItems: <list>
                checkout-offer-cost-not-set-error:
                  value:
                    code: CHECKOUT_OFFER_COST_NOT_SET_ERROR
                checkout-promotion-already-used-by-customer:
                  value:
                    code: CHECKOUT_PROMOTION_ALREADY_USED_BY_CUSTOMER
                    promotionId: <promotionid>
                    customerId: <string?>
                    normalizedEmailId: <string?>
                checkout-promotion-available-only-for-signed-customers:
                  value:
                    code: CHECKOUT_PROMOTION_AVAILABLE_ONLY_FOR_SIGNED_CUSTOMERS
                    promotionId: <promotionid>
                checkout-promotion-does-not-exists:
                  value:
                    code: CHECKOUT_PROMOTION_DOES_NOT_EXISTS
                    id: <promotionid>
                checkout-promotion-free-shipping-country-not-supported:
                  value:
                    code: CHECKOUT_PROMOTION_FREE_SHIPPING_COUNTRY_NOT_SUPPORTED
                    id: <promotionid>
                    country: <country>
                checkout-promotion-maximum-uses-limit-exceeded:
                  value:
                    code: CHECKOUT_PROMOTION_MAXIMUM_USES_LIMIT_EXCEEDED
                    id: <promotionid>
                checkout-promotion-not-allowed-for-customer-tier:
                  value:
                    code: CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TIER
                    customerTierId: <membershiptierid?>
                checkout-promotion-not-allowed-for-customer-twitch-tier:
                  value:
                    code: CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TWITCH_TIER
                    twitchTier: <string?>
                checkout-promotion-not-allowed-for-given-items:
                  value:
                    code: CHECKOUT_PROMOTION_NOT_ALLOWED_FOR_GIVEN_ITEMS
                checkout-stock-not-enough-quantity:
                  value:
                    code: CHECKOUT_STOCK_NOT_ENOUGH_QUANTITY
                    errors: <list>
                external-order-country-not-supported:
                  value:
                    code: EXTERNAL_ORDER_COUNTRY_NOT_SUPPORTED
                    country: <string>
                external-order-validation-failed:
                  value:
                    code: EXTERNAL_ORDER_VALIDATION_FAILED
                    errors: <list>
                external-order-variant-not-found:
                  value:
                    code: EXTERNAL_ORDER_VARIANT_NOT_FOUND
                    variantId: <offervariantid>
                gift-not-found:
                  value:
                    code: GIFT_NOT_FOUND
                    giftId: <giftid>
                message-validation-error:
                  value:
                    code: MESSAGE_VALIDATION_ERROR
                    reason: <string>
                order-items-no-longer-in-stock-error:
                  value:
                    code: ORDER_ITEMS_NO_LONGER_IN_STOCK_ERROR
                    variantIds: <list>
                payment-free-unavailable-non-zero:
                  value:
                    code: PAYMENT_FREE_UNAVAILABLE_NON_ZERO
                    id: <externalid>
                    value: <money>
                payment-paypal-auth-error:
                  value:
                    code: PAYMENT_PAYPAL_AUTH_ERROR
                    ex: <paypalhttpauthexception>
                payment-paypal-order-not-approved:
                  value:
                    code: PAYMENT_PAYPAL_ORDER_NOT_APPROVED
                    ex: <paypalhttpexception>
                payment-paypal-unknown-error:
                  value:
                    code: PAYMENT_PAYPAL_UNKNOWN_ERROR
                    ex: <paypalhttpexception>
                payment-provider-not-supported:
                  value:
                    code: PAYMENT_PROVIDER_NOT_SUPPORTED
                    provider: <string>
                payment-unprocessable-paypal-error:
                  value:
                    code: PAYMENT_UNPROCESSABLE_PAYPAL_ERROR
                    msg: <string>
                promotion-already-used-by-customer:
                  value:
                    code: PROMOTION_ALREADY_USED_BY_CUSTOMER
                    promotionId: <promotionid>
                    customerId: <customeridentifier>
                promotion-available-only-for-signed-customers:
                  value:
                    code: PROMOTION_AVAILABLE_ONLY_FOR_SIGNED_CUSTOMERS
                    promotionId: <promotionid>
                promotion-free-shipping-country-not-supported:
                  value:
                    code: PROMOTION_FREE_SHIPPING_COUNTRY_NOT_SUPPORTED
                    id: <promotionid>
                    country: <country>
                promotion-maximum-uses-limit-exceeded:
                  value:
                    code: PROMOTION_MAXIMUM_USES_LIMIT_EXCEEDED
                    id: <promotionid>
                promotion-missing-required-products:
                  value:
                    code: PROMOTION_MISSING_REQUIRED_PRODUCTS
                promotion-not-allowed-for-customer-tier:
                  value:
                    code: PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TIER
                    customerTierId: <membershiptierid?>
                promotion-not-allowed-for-customer-twitch-tier:
                  value:
                    code: PROMOTION_NOT_ALLOWED_FOR_CUSTOMER_TWITCH_TIER
                    customerTwitchTier: <promotionrequirements.twitchtier?>
                    allowedTwitchTiers: <list>
                promotion-not-allowed-for-given-items:
                  value:
                    code: PROMOTION_NOT_ALLOWED_FOR_GIVEN_ITEMS
                shipping-rates-error:
                  value:
                    code: SHIPPING_RATES_ERROR
                    errorMessage: <string?>
                unsupported-operation-for-manufacturer:
                  value:
                    code: UNSUPPORTED_OPERATION_FOR_MANUFACTURER
                    title: <string>
                    productId: <productid>
                    manufacturer: <manufacturer>
                variant-not-allowed-for-free-products:
                  value:
                    code: VARIANT_NOT_ALLOWED_FOR_FREE_PRODUCTS
        '402':
          description: 'Possible errors: `EXTERNAL_ORDER_NO_PAYMENT_METHOD`'
          content:
            application/json:
              examples:
                external-order-no-payment-method:
                  value:
                    code: EXTERNAL_ORDER_NO_PAYMENT_METHOD
                    shopId: <shopid>
        '404':
          description: >-
            Possible errors: `CHECKOUT_SHOP_NOT_FOUND_ERROR`,
            `CHECKOUT_VARIANT_NOT_FOUND_ERROR`, `DELIVERY_SHOP_NOT_FOUND_ERROR`,
            `OFFER_NOT_FOUND_ERROR`, `OFFER_VARIANT_NOT_FOUND_ERROR`,
            `PAYMENT_PAYPAL_TOKEN_EXPIRED`,
            `PRODUCT_CATALOG_PRODUCT_ID_NOT_FOUND`,
            `SHOP_TEAM_MEMBER_SHOP_NOT_FOUND_ERROR`, `STOCK_NOT_FOUND`
          content:
            application/json:
              examples:
                checkout-shop-not-found-error:
                  value:
                    code: CHECKOUT_SHOP_NOT_FOUND_ERROR
                    shopId: <shopid>
                checkout-variant-not-found-error:
                  value:
                    code: CHECKOUT_VARIANT_NOT_FOUND_ERROR
                    offerVariantId: <offervariantid>
                delivery-shop-not-found-error:
                  value:
                    code: DELIVERY_SHOP_NOT_FOUND_ERROR
                    shopId: <shopid>
                offer-not-found-error:
                  value:
                    code: OFFER_NOT_FOUND_ERROR
                    offerId: <offerid>
                offer-variant-not-found-error:
                  value:
                    code: OFFER_VARIANT_NOT_FOUND_ERROR
                    offerVariantId: <offervariantid>
                payment-paypal-token-expired:
                  value:
                    code: PAYMENT_PAYPAL_TOKEN_EXPIRED
                product-catalog-product-id-not-found:
                  value:
                    code: PRODUCT_CATALOG_PRODUCT_ID_NOT_FOUND
                    id: <productid>
                shop-team-member-shop-not-found-error:
                  value:
                    code: SHOP_TEAM_MEMBER_SHOP_NOT_FOUND_ERROR
                    shopId: <shopid>
                stock-not-found:
                  value:
                    code: STOCK_NOT_FOUND
                    id: <stockid>
        '406':
          description: 'Possible errors: `PAYMENT_INSTRUMENT_DECLINED`'
          content:
            application/json:
              examples:
                payment-instrument-declined:
                  value:
                    code: PAYMENT_INSTRUMENT_DECLINED
                    msg: <string>
        '409':
          description: >-
            Possible errors: `CHECKOUT_PROMOTION_REQUIRE_MINIMUM_ORDER_VALUE`,
            `EXTERNAL_ORDER_DUPLICATE`, `PROMOTION_REQUIRE_MINIMUM_ORDER_VALUE`
          content:
            application/json:
              examples:
                checkout-promotion-require-minimum-order-value:
                  value:
                    code: CHECKOUT_PROMOTION_REQUIRE_MINIMUM_ORDER_VALUE
                    minimumOrderValue: <money>
                external-order-duplicate:
                  value:
                    code: EXTERNAL_ORDER_DUPLICATE
                    externalOrderId: <string>
                promotion-require-minimum-order-value:
                  value:
                    code: PROMOTION_REQUIRE_MINIMUM_ORDER_VALUE
                    minimumOrderValue: <money>
        '422':
          description: 'Possible errors: `FULFILLMENT_ILLEGAL_STATE_ERROR`'
          content:
            application/json:
              examples:
                fulfillment-illegal-state-error:
                  value:
                    code: FULFILLMENT_ILLEGAL_STATE_ERROR
                    title: <string>
        '429':
          description: 'Rate limited: 100 requests / 10 seconds per shop.'
          content:
            application/json:
              examples:
                too-many-requests:
                  value:
                    code: OPEN_API_TOO_MANY_REQUESTS
                    title: Too many requests
                    status: 429
      security:
        - oauth:
            - order_write
        - basicAuth: []
components:
  schemas:
    com.fourthwall.openapi.model.CreateExternalOrderRequest:
      type: object
      properties:
        externalOrderId:
          type: string
          example: ETSY-123456789
          minLength: 1
        externalSource:
          type: string
          example: ETSY
          minLength: 1
        items:
          type: array
          items:
            $ref: >-
              #/components/schemas/com.fourthwall.openapi.model.ExternalOrderItemWithIdRequest
          minItems: 1
        shippingAddress:
          $ref: >-
            #/components/schemas/com.fourthwall.openapi.model.ExternalOrderAddressRequest
        billingAddress:
          $ref: >-
            #/components/schemas/com.fourthwall.openapi.model.ExternalOrderAddressRequest
        customerEmail:
          type: string
          example: customer@example.com
        metadata:
          type: object
          additionalProperties:
            type: string
        taxOverride:
          type: string
          description: >-
            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.
          enum:
            - COLLECT
            - SKIP
          example: SKIP
        taxOverrideReason:
          type: string
          description: Justification for the override. Required when taxOverride = SKIP.
          example: Customer is the merchant of record (resale)
      required:
        - billingAddress
        - externalOrderId
        - externalSource
        - items
        - shippingAddress
      title: Create External Order Request
    com.fourthwall.openapi.model.ExternalOrderV1:
      type: object
      properties:
        orderId:
          type: string
          format: uuid
          example: b1a5c9d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        externalOrderId:
          type: string
          example: ETSY-123456789
        externalSource:
          type: string
          example: ETSY
        friendlyId:
          type: string
          example: T4YTE8HA
        status:
          type: string
          example: CONFIRMED
        items:
          type: array
          items:
            $ref: >-
              #/components/schemas/com.fourthwall.openapi.model.ExternalOrderItemV1
        shippingAddress:
          $ref: >-
            #/components/schemas/com.fourthwall.openapi.model.ExternalOrderAddressV1
        costs:
          $ref: >-
            #/components/schemas/com.fourthwall.openapi.model.ExternalOrderCostsV1
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - costs
        - createdAt
        - externalOrderId
        - externalSource
        - friendlyId
        - items
        - orderId
        - shippingAddress
        - status
        - updatedAt
      title: External Order
    com.fourthwall.openapi.model.ExternalOrderItemWithIdRequest:
      type: object
      properties:
        variantId:
          type: string
          example: c2b6d0e3-4f5g-6h7i-8j9k-0l1m2n3o4p5q
          minLength: 1
        quantity:
          type: integer
          format: int32
          example: 2
          minimum: 1
        externalLineItemId:
          type: string
          example: etsy-line-item-123
      required:
        - quantity
        - variantId
      title: External Order Item With Id Request
    com.fourthwall.openapi.model.ExternalOrderAddressRequest:
      type: object
      properties:
        firstName:
          type: string
          example: John
          minLength: 1
        lastName:
          type: string
          example: Doe
          minLength: 1
        address1:
          type: string
          example: 123 Main Street
          minLength: 1
        address2:
          type: string
          example: Apt 4B
        city:
          type: string
          example: San Francisco
          minLength: 1
        state:
          type: string
          example: CA
        zip:
          type: string
          example: '94105'
          minLength: 1
        country:
          type: string
          example: US
          minLength: 1
        phone:
          type: string
          example: +1-555-123-4567
      required:
        - address1
        - city
        - country
        - firstName
        - lastName
        - zip
      title: External Order Address Request
    com.fourthwall.openapi.model.ExternalOrderItemV1:
      type: object
      properties:
        offerId:
          type: string
          format: uuid
        variantId:
          type: string
          format: uuid
        quantity:
          type: integer
          format: int32
          example: 2
        externalLineItemId:
          type: string
          example: etsy-line-item-123
        unitCost:
          $ref: '#/components/schemas/Money'
        totalCost:
          $ref: '#/components/schemas/Money'
        itemFulfillmentFee:
          $ref: '#/components/schemas/Money'
        itemShippingCost:
          $ref: '#/components/schemas/Money'
        itemTotalCreatorCost:
          $ref: '#/components/schemas/Money'
      required:
        - itemFulfillmentFee
        - itemShippingCost
        - itemTotalCreatorCost
        - offerId
        - quantity
        - totalCost
        - unitCost
        - variantId
      title: External Order Item
    com.fourthwall.openapi.model.ExternalOrderAddressV1:
      type: object
      properties:
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        address1:
          type: string
          example: 123 Main Street
        address2:
          type: string
          example: Apt 4B
        city:
          type: string
          example: San Francisco
        state:
          type: string
          example: CA
        zip:
          type: string
          example: '94105'
        country:
          type: string
          example: US
        phone:
          type: string
          example: +1-555-123-4567
      required:
        - address1
        - city
        - country
        - firstName
        - lastName
        - zip
      title: External Order Address
    com.fourthwall.openapi.model.ExternalOrderCostsV1:
      type: object
      properties:
        fulfillmentFee:
          $ref: '#/components/schemas/Money'
        manufacturingCost:
          $ref: '#/components/schemas/Money'
        shippingCost:
          $ref: '#/components/schemas/Money'
        totalCreatorCost:
          $ref: '#/components/schemas/Money'
      required:
        - fulfillmentFee
        - manufacturingCost
        - shippingCost
        - totalCreatorCost
      title: External Order Costs
    Money:
      type: object
      properties:
        value:
          type: number
          example: 10
          minimum: 0
        currency:
          type: string
          example: USD
      required:
        - currency
        - value
      title: Money
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: >-
            https://auth.staging.fourthwall.com/auth/realms/Fourthwall/protocol/openid-connect/auth
          scopes:
            donation_read: donation_read
            order_read: order_read
            order_write: order_write
            fulfillment_write: fulfillment_write
            giveaway_read: giveaway_read
            giveaway_write: giveaway_write
            memberships_read: memberships_read
            memberships_write: memberships_write
            promotions_write: promotions_write
            promotions_read: promotions_read
            offer_read: offer_read
            offer_write: offer_write
            shop_read: shop_read
            thankyou_read: thankyou_read
            thankyou_write: thankyou_write
            webhook_read: webhook_read
            webhook_write: webhook_write
            media_read: media_read
            media_write: media_write
            analytics_read: analytics_read
            samples_read: samples_read
            samples_write: samples_write
            dns_read: dns_read
            dns_write: dns_write
            settings_read: settings_read
            payout_read: payout_read
            integrations_read: integrations_read
    basicAuth:
      type: http
      scheme: basic

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.