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

# Create an order

> Creates an order and returns its `checkout_url`, where the customer picks a payment method and pays. Prices, stock, coupons, product rules, fraud checks, shipping and affiliate attribution work exactly as on your storefront.

For physical products send `shipping_address`; without it the customer enters the address on the checkout page. The order expires after 3 hours if unpaid.

**Permission:** `orders:write`



## OpenAPI

````yaml /api-reference/openapi/user-api.yaml post /invoices
openapi: 3.0.3
info:
  title: PapelShip Store API
  version: 1.0.0
  description: >-
    Manage your PapelShip store from your own systems: create orders, sync
    products and stock, ship physical orders, answer support tickets and react
    to events.


    Every request needs your API key in `x-api-key` and your store ID in
    `x-store-hash`. Amounts are integers in minor units (`2999` = 29.99). Dates
    are ISO 8601 in UTC.
  contact:
    name: PapelShip Support
    email: support@papelship.com
    url: https://papelship.com
servers:
  - url: https://app.papelship.com/api/v1
    description: Production
security:
  - ApiKey: []
    StoreHash: []
tags:
  - name: Account
    description: Your key, store and payment methods.
  - name: Orders
    description: Create orders, take manual payments, cancel, refund and read deliveries.
  - name: Products
    description: Products and their settings.
  - name: Variants & stock
    description: Variants, physical stock and license keys.
  - name: Product content
    description: Media, SEO, payment methods, files and stock alerts.
  - name: Categories
    description: Organise products.
  - name: Groups
    description: Collections of products.
  - name: Coupons
    description: Discount codes.
  - name: Customers
    description: Buyers and their history.
  - name: Blocklist
    description: Emails and IPs that can't place orders.
  - name: Reviews
    description: Customer reviews.
  - name: Support
    description: Support tickets.
  - name: Subscriptions
    description: Recurring products and auto-renewals.
  - name: Fulfillment
    description: Ship physical orders.
  - name: Returns
    description: Return requests.
  - name: Shipping settings
    description: Zones, rates and locations.
  - name: Webhooks
    description: Endpoints, deliveries and event types.
  - name: Affiliates
    description: Partner programme.
  - name: Analytics
    description: Sales summary.
paths:
  /invoices:
    post:
      tags:
        - Orders
      summary: Create an order
      description: >-
        Creates an order and returns its `checkout_url`, where the customer
        picks a payment method and pays. Prices, stock, coupons, product rules,
        fraud checks, shipping and affiliate attribution work exactly as on your
        storefront.


        For physical products send `shipping_address`; without it the customer
        enters the address on the checkout page. The order expires after 3 hours
        if unpaid.


        **Permission:** `orders:write`
      operationId: createInvoice
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            maxLength: 255
          description: >-
            Unique key (for example a UUID) that makes retries safe. The first
            response is stored for 24 hours and replayed for retries with the
            same key and body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_email:
                  type: string
                  format: email
                  description: Buyer email. Receives the invoice email and the delivery.
                  example: buyer@example.com
                delivery_email:
                  type: string
                  format: email
                  description: Send the delivery to a different address.
                items:
                  type: array
                  description: >-
                    1–50 lines. Prices come from your catalogue; you cannot set
                    them.
                  items:
                    type: object
                    properties:
                      product_id:
                        oneOf:
                          - type: string
                          - type: integer
                        description: Product hash ID (or numeric ID).
                        example: a1B2c3D4e5F6
                      variant_id:
                        type: integer
                        description: Required for products with variants.
                      quantity:
                        type: integer
                        default: 1
                        minimum: 1
                        maximum: 10000
                      donation_amount_cents:
                        type: integer
                        description: Required for donation products.
                    required:
                      - product_id
                  minItems: 1
                  maxItems: 50
                coupon_code:
                  type: string
                  description: >-
                    Applied if valid for these products. An invalid coupon is
                    ignored.
                  example: SUMMER10
                currency:
                  type: string
                  description: Must match the products' currency. Defaults to it.
                  example: USD
                expected_total_cents:
                  type: integer
                  description: >-
                    Optional safety check. If the server total differs by more
                    than 1 cent, the call fails with `TOTAL_MISMATCH`.
                custom_fields:
                  type: object
                  properties: {}
                  description: Answers to your checkout fields, keyed by field key.
                  additionalProperties:
                    type: string
                shipping_address:
                  $ref: '#/components/schemas/ShippingAddress'
                shipping_rate_id:
                  type: integer
                  description: >-
                    Rate from POST /shipping/quote. Without it the cheapest rate
                    is used.
                customer_ip:
                  type: string
                  description: >-
                    Buyer's IP address. Enables your fraud, VPN and blocklist
                    rules for this order.
                  example: 203.0.113.10
                affiliate_code:
                  type: string
                  description: Partner link code to credit (affiliate programme).
                  example: alex
                send_email:
                  type: boolean
                  description: Send the invoice email to the customer.
                  default: true
                metadata:
                  type: object
                  properties: {}
                  description: >-
                    Up to 20 keys (≤40 chars) with string values (≤500 chars).
                    Returned on the order and in webhooks of your systems.
                  additionalProperties:
                    type: string
                  example:
                    order_ref: WEB-1042
              required:
                - customer_email
                - items
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  invoice:
                    $ref: '#/components/schemas/Invoice'
                required:
                  - success
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ShippingAddress:
      type: object
      properties:
        full_name:
          type: string
          example: Alex Morgan
        company:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
          example: +44 20 7946 0958
        email:
          type: string
          nullable: true
        country_code:
          type: string
          description: ISO 3166-1 alpha-2.
          example: GB
        region:
          type: string
          description: State, province or county.
          nullable: true
          example: Greater London
        city:
          type: string
          nullable: true
          example: London
        district:
          type: string
          nullable: true
        line1:
          type: string
          example: 221B Baker Street
        line2:
          type: string
          nullable: true
        postal_code:
          type: string
          nullable: true
          example: NW1 6XE
    Invoice:
      type: object
      properties:
        id:
          type: string
          description: Public order ID. Use it in every /invoices/{id} call.
          example: c35ffd-19a1b2c3d4e-8c7a20
        object:
          type: string
          enum:
            - invoice
          example: invoice
        status:
          type: string
          description: >-
            `pending` waits for payment; `completed` is paid and delivered;
            `cancelled` and `expired` are closed.
          enum:
            - pending
            - payment_pending
            - payment_processing
            - partial_payment
            - manual_review_pending
            - completed
            - cancelled
            - expired
          example: pending
        currency:
          type: string
          example: USD
        total_cents:
          type: integer
          description: Total including shipping.
          example: 3499
        shipping_cents:
          type: integer
          example: 500
        refunded_cents:
          type: integer
          example: 0
        refund_status:
          type: string
          enum:
            - not_refunded
            - partially_refunded
            - fully_refunded
          example: not_refunded
        customer_email:
          type: string
          example: buyer@example.com
        delivery_email:
          type: string
          example: buyer@example.com
        coupon_code:
          type: string
          nullable: true
        payment_method:
          type: string
          description: Method the customer chose, for example `STRIPE`, `BITCOIN`, `USDT`.
          nullable: true
          example: STRIPE
        country:
          type: string
          nullable: true
          example: United Kingdom
        fraud_score:
          type: integer
          description: 0–100. Higher is riskier.
          example: 0
        source:
          type: string
          description: Where the order came from.
          enum:
            - storefront
            - api
            - embed
          example: api
        metadata:
          type: object
          properties: {}
          description: Your own key/value pairs (strings).
          additionalProperties:
            type: string
          example:
            order_ref: WEB-1042
        requires_shipping:
          type: boolean
          example: false
        fulfillment_status:
          type: string
          enum:
            - unfulfilled
            - partially_fulfilled
            - fulfilled
            - delivered
            - returned
            - cancelled
          nullable: true
        shipping_method:
          type: object
          properties:
            name:
              type: string
            carrier_code:
              type: string
            min_days:
              type: integer
            max_days:
              type: integer
          nullable: true
        checkout_url:
          type: string
          description: Hosted page where the customer pays.
          example: https://app.papelship.com/invoice/c35ffd-19a1b2c3d4e-8c7a20
        created_at:
          type: string
          format: date-time
          example: '2026-10-04T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-10-04T12:00:00.000Z'
        expires_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-10-04T12:00:00.000Z'
        paid_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-10-04T12:00:00.000Z'
        items:
          type: array
          description: Included on detail responses and with `expand=items` on lists.
          items:
            $ref: '#/components/schemas/InvoiceItem'
        shipping_address:
          allOf:
            - $ref: '#/components/schemas/ShippingAddress'
          description: Detail responses only.
        custom_fields:
          type: object
          properties: {}
          description: Answers to your checkout fields. Detail responses only.
          additionalProperties:
            type: string
    InvoiceItem:
      type: object
      properties:
        id:
          type: integer
          example: 8812
        product_id:
          type: string
          description: Product hash ID.
          nullable: true
          example: a1B2c3D4e5F6
        product_name:
          type: string
          example: Pro License
        variant_id:
          type: integer
          nullable: true
        quantity:
          type: integer
          example: 1
        unit_price_cents:
          type: integer
          example: 2999
        discount_percent:
          type: number
          example: 0
        total_cents:
          type: integer
          example: 2999
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Machine-readable error code. Branch on this, not on the message.
          example: VALIDATION_FAILED
        error:
          type: string
          description: Human-readable message.
          example: customer_email must be a valid email address
        details:
          type: object
          properties: {}
          description: Extra context, for example `field` for validation errors.
          additionalProperties: true
        request_id:
          type: string
          description: Include this when you contact support.
          example: req_7YbK2mQ9xP1cRt4v
      required:
        - success
        - code
        - error
  responses:
    Unauthorized:
      description: >-
        Missing, invalid or expired API key.


        Codes: `MISSING_API_KEY`, `MISSING_STORE_HASH`, `INVALID_API_KEY`,
        `API_KEY_EXPIRED`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: INVALID_API_KEY
            error: Invalid API Key
            request_id: req_7YbK2mQ9xP1cRt4v
    Forbidden:
      description: >-
        The key is not allowed to do this.


        Codes: `INSUFFICIENT_SCOPE`, `IP_NOT_ALLOWED`, `STORE_NOT_ALLOWED`,
        `STORE_API_NOT_IN_PLAN`, `FEATURE_NOT_ENABLED`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: INSUFFICIENT_SCOPE
            error: This API key needs the orders:write permission
            request_id: req_7YbK2mQ9xP1cRt4v
    NotFound:
      description: |-
        The record does not exist in this store.

        Codes: `NOT_FOUND`, `STORE_NOT_FOUND`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: NOT_FOUND
            error: Invoice not found
            request_id: req_7YbK2mQ9xP1cRt4v
    Conflict:
      description: |-
        The record is in a state that does not allow this action.

        Codes: `IDEMPOTENCY_IN_PROGRESS`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: INVOICE_PAID
            error: A paid order cannot be cancelled. Refund it instead.
            request_id: req_7YbK2mQ9xP1cRt4v
    ValidationFailed:
      description: |-
        A field is missing or invalid. `details.field` names it.

        Codes: `VALIDATION_FAILED`, `IDEMPOTENCY_KEY_REUSED`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: VALIDATION_FAILED
            error: customer_email must be a valid email address
            request_id: req_7YbK2mQ9xP1cRt4v
    RateLimited:
      description: >-
        Too many requests. Wait `Retry-After` seconds.


        Codes: `RATE_LIMITED` (300 requests per minute per key),
        `STORE_API_MONTHLY_QUOTA_EXCEEDED` (your plan's monthly quota).
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: RATE_LIMITED
            error: Too many requests. The limit is 300 requests per minute per key.
            request_id: req_7YbK2mQ9xP1cRt4v
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Store API key (`pk_live_...`). Create it in **Developers › API
        keys**.
    StoreHash:
      type: apiKey
      in: header
      name: x-store-hash
      description: >-
        The ID of the store the request is for. Shown in **Developers › API
        keys**.

````

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