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

# Create an Orders export

> Trigger a one-off Orders export to your own GCS or S3 bucket. The export contains one row per order. By default it uses the default order columns (which include the customer type, first-time vs. returning); if you pass an explicit `columns` list you get exactly those columns. Product ids/SKUs, order tags, and the order source name are available as optional columns. Poll the returned `id` with `GET /data-export/result/{export_id}`.

<div className="nb-api-tables nb-field-table">
  ## Headers

  | Header | Description |
  | :- | :- |
  | `Authorization` <span className="nb-req">required</span> | Your Northbeam API key |
  | `Data-Client-ID` <span className="nb-req">required</span> | Your Northbeam client ID |
  | `Content-Type` <span className="nb-req">required</span> | `application/json` |

  ## Body

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>bucket\_name</code> <span className="nb-req">required</span></td><td>string</td><td>Name of the external GCS or S3 bucket to export to.</td></tr><tr><td><code>aws\_role</code></td><td>string, nullable</td><td>AWS role ARN with access to the S3 bucket (required for S3 exports).</td></tr><tr><td><code>region</code></td><td>string, nullable</td><td>AWS region of the S3 bucket (required for S3 exports).</td></tr><tr><td><code>export\_file\_name</code></td><td>string</td><td>Name of the exported file. A default name is used if omitted.<br />Minimum string length: <code>3</code><br />Pattern: <code>^(?!/)(?!.\*//)\[A-Za-z0-9\_/-]+(?\<!/)\$</code></td></tr><tr><td><code>start\_date</code> <span className="nb-req">required</span></td><td>string (date-time)</td><td>Start of the export window (inclusive).</td></tr><tr><td><code>end\_date</code> <span className="nb-req">required</span></td><td>string (date-time)</td><td>End of the export window (exclusive).</td></tr><tr><td><code>columns</code></td><td>string\[]</td><td>Optional list of column ids to include, in order. When omitted, the default columns are used. When provided, it must be a non-empty list of distinct ids, and you get exactly the columns you list — any subset of the allowed ids is valid and nothing is mandatory (<code>customer\_type</code> is a default column, so include it here if you want it). <code>products</code> is a single column of comma-separated SKUs, falling back to the product id when a SKU is missing.<br />Minimum array length: <code>1</code><br />Items must be unique.</td></tr></tbody></table></div>

  ## Responses

  | Status | Description |
  | :- | :- |
  | `201` | Orders export created successfully |
  | `401` | Unauthorized |
  | `422` | Invalid Body Params |
  | `429` | Too many requests |
  | `500` | Internal server error |

  ### `201` response body

  <div className="nb-table-wrap"><table className="nb-main-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code> <span className="nb-req">required</span></td><td>string (uuid)</td><td /></tr></tbody></table></div>
</div>


## OpenAPI

````yaml openapi/data-export-v1.json POST /data-export/orders
openapi: 3.0.0
info:
  title: API - DATA EXPORT - V1
  version: '1'
  description: API for exporting data from Northbeam
  termsOfService: https://www.northbeam.io/terms
servers:
  - url: https://api.northbeam.io/v1/exports
security:
  - api_key: []
    client_id: []
tags:
  - name: Sales Attribution
    description: >-
      Export performance metrics by attribution model, window, and accounting
      mode. Use the helper endpoints to discover the models, metrics, and
      breakdowns available to your account before creating the export.
  - name: Orders
    description: >-
      Export your orders (one row per order) with product information to your
      own GCS or S3 bucket.
  - name: Results
    description: Poll for and download a completed export. Shared by every report type.
paths:
  /data-export/orders:
    post:
      tags:
        - Orders
      summary: Create an Orders export (orders + product information)
      description: >-
        Trigger a one-off Orders export to your own GCS or S3 bucket. The export
        contains one row per order. By default it uses the default order columns
        (which include the customer type, first-time vs. returning); if you pass
        an explicit `columns` list you get exactly those columns. Product
        ids/SKUs, order tags, and the order source name are available as
        optional columns. Poll the returned `id` with `GET
        /data-export/result/{export_id}`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrdersExport'
      responses:
        '201':
          description: Orders export created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    format: uuid
        '401':
          description: Unauthorized
        '422':
          description: Invalid Body Params
        '429':
          description: Too many requests
        '500':
          description: Internal server error
components:
  schemas:
    CreateOrdersExport:
      type: object
      additionalProperties: false
      description: >-
        Request to trigger a one-off Orders export (orders plus product
        information) to your own storage bucket. For an S3 destination provide
        both `aws_role` and `region`; omit them for a GCS destination.
      required:
        - bucket_name
        - start_date
        - end_date
      properties:
        bucket_name:
          description: Name of the external GCS or S3 bucket to export to.
          type: string
        aws_role:
          description: AWS role ARN with access to the S3 bucket (required for S3 exports).
          type: string
          nullable: true
        region:
          description: AWS region of the S3 bucket (required for S3 exports).
          type: string
          nullable: true
        export_file_name:
          description: Name of the exported file. A default name is used if omitted.
          type: string
          minLength: 3
          pattern: ^(?!/)(?!.*//)[A-Za-z0-9_/-]+(?<!/)$
        start_date:
          description: Start of the export window (inclusive).
          type: string
          format: date-time
        end_date:
          description: End of the export window (exclusive).
          type: string
          format: date-time
        columns:
          description: >-
            Optional list of column ids to include, in order. When omitted, the
            default columns are used. When provided, it must be a non-empty list
            of distinct ids, and you get exactly the columns you list — any
            subset of the allowed ids is valid and nothing is mandatory
            (`customer_type` is a default column, so include it here if you want
            it). `products` is a single column of comma-separated SKUs, falling
            back to the product id when a SKU is missing.
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            enum:
              - order_id
              - order_number
              - order_ts
              - platform
              - order_revenue_total
              - refund_amount_in_dollars
              - attributed
              - customer_type
              - customer_first_name_sha256
              - customer_email_sha256
              - customer_phone_sha256
              - customer_city_sha256
              - customer_country_code_sha256
              - customer_province_code_sha256
              - customer_zip_sha256
              - ip_address
              - products
              - order_tags
              - source_name
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    client_id:
      type: apiKey
      name: Data-Client-ID
      in: header

````