> ## Documentation Index > Fetch the complete documentation index at: https://docs.snappy.com/llms.txt > Use this file to discover all available pages before exploring further. # Get orders > Use this endpoint to retrieve a paginated list of orders for the calling Company. Use this when you want to browse orders, look up orders matching specific idempotency keys, or sync recent order activity to your system. ###### Filtering options: - `filter[status]` - exact match on order status. One of active (in progress or delivered) or cancelled. - `filter[idempotencyKey]` - comma-separated list of idempotency keys. Returns orders matching any of the supplied keys. - `filter[createdAt][gte]` - return orders created at or after this ISO 8601 timestamp. - `filter[createdAt][lte]` - return orders created at or before this ISO 8601 timestamp. - `Snappy-Account-Id` header - optional account scoping. - `Snappy-Company-Id` header - optional company scoping. ###### Pagination and sorting: - `page[number]` - 1-indexed page number (default 1). - `page[size]` - number of orders per page (max 300, default 100). - `sort` - -createdAt (default, newest first) or createdAt (oldest first). ###### Please note: - Uses page-number pagination (not cursor, unlike product list endpoints). The response includes a top-level links object with first, next, and prev URLs. - The `filter[idempotencyKey]` filter is useful for looking up orders created by specific replays. Follow the order with `GET /v3/orders/{orderId}` if you need additional detail beyond what's in the list response. - Both Direct Fulfillment orders and Triggered Gifting orders are returned by this endpoint - they share the same response shape. - PII masking applies based on the scope used for the request. #### Permissions - Requires: `orders:read:masked` or `orders:read:unmasked` ## OpenAPI ````yaml get /v3/orders openapi: 3.0.3 info: title: Snappy Public API v3 version: 3.0.0 contact: name: Snappy Support email: info@snappy.com description: >- Welcome to the Snappy API reference documentation! You can use this API to integrate with Snappy and spread smiles to your employees/clients/customers and much more. So let's get started! servers: - url: https://api.snappy.com/public-api description: Base API URL - url: https://mtls-api.snappy.com/public-api description: >- ## mTLS URL You can also use mTLS to enhance your API security. To get your specific certificates please contact our support. Once you configure the certificated correctly, you need to also update endpoints to use the following secure api base URL: security: [] tags: - name: Products description: >- Use these endpoints to retrieve products and tags for building catalog and browse experiences in your UI. - name: Collections description: >- Use these endpoints to retrieve products within curated collections for marketplace and browse experiences. - name: Variants description: >- Use these endpoints to retrieve variants, variant pricing, and country availability for orderable product SKUs. - name: Billing Methods description: >- A **Billing Method** is the funding source attached to an **Account** - for example, a Purchase Order (PO), Invoice, Prepay deposit, or Credit Card. Use these endpoints to retrieve billing method details such as remaining balance, status, and expiration. - name: Accounts description: >- An **Account** is a sub-entity within a **Company**, used to organize campaigns and gift sends. Use these endpoints to list, retrieve, and create accounts. - name: API Keys description: >- Use these endpoints to manage API keys for programmatic access. Key management requires company owner privileges. - name: Orders description: >- Use these endpoints to place, retrieve, cancel, and validate orders and shipping addresses. paths: /v3/orders: get: tags: - Orders summary: List orders - v3 description: >- Use this endpoint to retrieve a paginated list of orders for the calling Company. Use this when you want to browse orders, look up orders matching specific idempotency keys, or sync recent order activity to your system. ###### Filtering options: - `filter[status]` - exact match on order status. One of active (in progress or delivered) or cancelled. - `filter[idempotencyKey]` - comma-separated list of idempotency keys. Returns orders matching any of the supplied keys. - `filter[createdAt][gte]` - return orders created at or after this ISO 8601 timestamp. - `filter[createdAt][lte]` - return orders created at or before this ISO 8601 timestamp. - `Snappy-Account-Id` header - optional account scoping. - `Snappy-Company-Id` header - optional company scoping. ###### Pagination and sorting: - `page[number]` - 1-indexed page number (default 1). - `page[size]` - number of orders per page (max 300, default 100). - `sort` - -createdAt (default, newest first) or createdAt (oldest first). ###### Please note: - Uses page-number pagination (not cursor, unlike product list endpoints). The response includes a top-level links object with first, next, and prev URLs. - The `filter[idempotencyKey]` filter is useful for looking up orders created by specific replays. Follow the order with `GET /v3/orders/{orderId}` if you need additional detail beyond what's in the list response. - Both Direct Fulfillment orders and Triggered Gifting orders are returned by this endpoint - they share the same response shape. - PII masking applies based on the scope used for the request. #### Permissions - Requires: `orders:read:masked` or `orders:read:unmasked` parameters: - schema: type: integer minimum: 1 default: 1 description: Page number, starting at 1. Defaults to 1 when omitted. example: 1 required: false description: Page number, starting at 1. Defaults to 1 when omitted. name: page[number] in: query - schema: type: integer minimum: 1 maximum: 300 default: 100 description: >- Page size. Must be between 1 and 300. Defaults to 100 when omitted. example: 100 required: false description: Page size. Must be between 1 and 300. Defaults to 100 when omitted. name: page[size] in: query - schema: $ref: '#/components/schemas/OrdersGetV3Sort' required: false description: >- Sort order. `-createdAt` (default) returns newest first; `createdAt` returns oldest first. name: sort in: query - schema: $ref: '#/components/schemas/OrdersGetV3StatusFilter' required: false description: Filter by order status. name: filter[status] in: query - schema: type: array items: type: string minLength: 1 minItems: 1 uniqueItems: true description: >- Comma-separated list of idempotency keys. Returns orders matching any of the supplied keys. example: - idem-abc - idem-def required: false description: >- Comma-separated list of idempotency keys. Returns orders matching any of the supplied keys. name: filter[idempotencyKey] in: query style: form explode: false - schema: type: object properties: gte: type: string format: date-time lte: type: string format: date-time additionalProperties: false description: >- Filter by order creation timestamp. Accepts full ISO timestamps via `filter[createdAt][gte]` and `filter[createdAt][lte]`. required: false description: >- Filter by order creation timestamp. Accepts full ISO timestamps via `filter[createdAt][gte]` and `filter[createdAt][lte]`. name: filter[createdAt] in: query - schema: type: string description: Optional account identifier for swag validation/filtering. example: acc123456 required: false description: Optional account identifier for swag validation/filtering. name: snappy-account-id in: header - schema: type: string description: Optional company identifier for swag validation/filtering. example: cmp123456 required: false description: Optional company identifier for swag validation/filtering. name: snappy-company-id in: header responses: '200': description: Page of orders plus pagination links. content: application/json: schema: $ref: '#/components/schemas/OrdersGetV3Response' '400': description: Bad Request - Invalid query parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' security: - ApiKeyAuthentication: [] components: schemas: OrdersGetV3Sort: type: string enum: - createdAt - '-createdAt' default: '-createdAt' description: >- Sort order. `-createdAt` (default) returns newest first; `createdAt` returns oldest first. example: '-createdAt' OrdersGetV3StatusFilter: type: string enum: - active - cancelled description: Filter by order status. example: active OrdersGetV3Response: type: object properties: data: type: array items: $ref: '#/components/schemas/OrderResponseV3' description: Orders matching the query, ordered per `sort`. links: $ref: '#/components/schemas/PaginationLinksV3' required: - data - links description: >- JSON:API list envelope. Returns the page of orders plus pagination links. ErrorResponseV3: type: object properties: message: type: string description: Human-readable error message. example: Product not found. errorCode: type: string description: Structured error code. example: 404_PROD_001 errors: type: array items: type: object properties: message: type: string example: Product with id 'q1w2e3r4t5' was not found path: type: string description: Dot-separated path to the field that caused the error. example: pathParameters.productId errorCode: type: string example: 404_PROD_001 required: - message - path description: Optional field-level error details. required: - message - errorCode description: Standard v3 error envelope. OrderResponseV3: type: object properties: id: type: string description: Unique identifier for the order. example: G7nR4bD9mK createdAt: type: string format: date-time description: Timestamp when the order was created (ISO 8601). example: '2026-05-27T10:30:00.000Z' status: type: string enum: - active - completed - cancelled - refunded description: >- Overall commercial lifecycle of the order. `active`: order is being processed or in fulfillment. `completed`: order has been fulfilled and finalized. `cancelled`: order was cancelled before fulfillment. `refunded`: order was returned and refunded after delivery. example: active fulfillmentStatus: type: string enum: - unfulfilled - fulfilled - cancelled description: >- Aggregated fulfillment status across all line items. `unfulfilled`: no fulfillments exist. `fulfilled`: all line items covered by a fulfillment. `cancelled`: order fulfillment was cancelled. example: unfulfilled tags: type: array items: type: string description: Tags associated with this order. example: [] idempotencyKey: type: string description: >- Idempotency key supplied at order creation. Useful for correlating an external request to its order. example: order-2026-05-13-abc cancellationDetails: $ref: '#/components/schemas/CancellationDetailsV3' lineItems: type: array items: $ref: '#/components/schemas/LineItemV3' description: Products included in this order. fulfillments: type: array items: $ref: '#/components/schemas/FulfillmentV3' description: >- Fulfillment records for this order. Empty when the order has not yet been shipped or when tracking information is unavailable. recipient: $ref: '#/components/schemas/OrderResponseRecipientV3' shippingAddress: $ref: '#/components/schemas/ShippingAddressV3' metadata: $ref: '#/components/schemas/Metadata' required: - id - createdAt - status - fulfillmentStatus - tags - cancellationDetails - lineItems - fulfillments - recipient - shippingAddress - metadata description: >- Order details including line items, recipient, shipping address, fulfillments, and tracking information. PaginationLinksV3: type: object properties: first: type: string nullable: true description: Link to the first page. example: >- /v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=1 next: type: string nullable: true description: Link to the next page, or `null` on the final page. example: >- /v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=2 prev: type: string nullable: true description: Link to the previous page, or `null` when not applicable. example: null required: - first - next - prev description: >- Top-level JSON:API-style pagination links for paginated list responses. `first`, `next`, and `prev` are all required and all nullable. `prev` is `null` on cursor-paginated endpoints (backward navigation not supported). CancellationDetailsV3: type: object nullable: true properties: cancelledAt: type: string format: date-time description: Timestamp when the order was cancelled (ISO 8601). example: '2026-05-27T15:57:00.000Z' cancellationReason: type: string enum: - customer_requested description: Reason the order was cancelled. example: customer_requested description: Populated only when the order is `cancelled`; `null` otherwise. LineItemV3: type: object properties: variantId: type: string description: Variant ID of the ordered product. example: v_abc12345 title: type: string description: Product title at the time of order. example: Premium Gift Card quantity: type: integer minimum: 1 description: Quantity ordered. example: 1 required: - variantId - quantity FulfillmentV3: type: object properties: id: type: string description: Unique identifier for this fulfillment record. example: tr_abc123 status: type: string enum: - confirmed - processing - inTransit - outForDelivery - delivered description: >- Carrier delivery progress for a single fulfillment. `confirmed`: order received by the vendor. `processing`: being prepared for shipment. `inTransit`: shipped and in transit. `outForDelivery`: out for delivery. `delivered`: delivered to the recipient. example: inTransit trackingCompany: type: string description: Carrier name (e.g. UPS, USPS, FedEx). example: UPS trackingInfo: $ref: '#/components/schemas/TrackingInfoV3' fulfillmentLineItems: type: array items: $ref: '#/components/schemas/LineItemV3' description: Line items included in this fulfillment. required: - fulfillmentLineItems OrderResponseRecipientV3: type: object properties: firstName: type: string description: Recipient's first name. example: John lastName: type: string description: Recipient's last name. example: Doe email: type: string description: Recipient's email address. example: john.doe@example.com phone: type: string description: Recipient's phone number in E.164 format. example: '+15555555555' required: - firstName ShippingAddressV3: type: object properties: address1: type: string description: Primary street address line. example: 123 Main St address2: type: string description: Secondary address line (apartment, suite, etc.). example: Suite A city: type: string description: City name. example: New York provinceCode: type: string description: State or province code (e.g., NY, CA, ON). example: NY countryCode: type: string description: Two-letter ISO 3166-1 alpha-2 country code. example: US postalCode: type: string description: Postal code or ZIP code. example: '10001' Metadata: type: object nullable: true additionalProperties: type: string maxLength: 500 pattern: ^[a-zA-Z0-9\s\-_.]+$ maxProperties: 50 description: >- Custom key-value pairs attached at order creation. May include `externalRecipientId` for correlating with your internal systems. Returns `null` when no metadata was supplied. example: key1: value1 key2: value2 TrackingInfoV3: type: object properties: number: type: string description: Carrier tracking number. example: 1Z9999W99999999999 url: type: string description: Tracking page URL provided by the carrier. example: https://www.ups.com/track?tracknum=1Z9999W99999999999 securitySchemes: ApiKeyAuthentication: type: apiKey in: header name: X-Api-Key description: |- ## Company Level Authentication Include your API key in the `X-Api-Key` header for every request: ``` X-Api-Key: YOUR_API_KEY ``` ````