> ## Documentation Index > Fetch the complete documentation index at: https://docs.alura.io/llms.txt > Use this file to discover all available pages before exploring further. # Get an order > One order (Etsy receipt) of your connected Etsy shops by its order ID: status, totals, the buyer's name, the shipping address, the buyer's and the seller's messages, the gift message, every item (with the listing image), the shipments and the refunds, as Alura last stored them from Etsy. An address Etsy withholds (Preferred Partner regions) is `null` with `shipping_address_error: etsy_restricted`, and an order of only digital items has none (`no_physical_items`). `expand=payment` adds Etsy's payment: gross, fees and net (null with `payment_error: not_fetched` when Alura has not stored it). The other `expand=` values are for MCP clients, which get messages and the address only when they ask; over REST these are always included. Holds buyer personal data, as Etsy provides it. An order outside the workspace is 404. Needs the `orders:read` scope and the Customer analytics workspace permission. Costs 1 API credit per call, expansions included. Cost: 1 API credit per call. ## OpenAPI ````yaml /openapi.json get /v1/workspace/orders/{id} openapi: 3.1.0 info: title: Alura API version: 1.0.0 description: Etsy market research for scripts and AI assistants. servers: - url: https://api.alura.io security: - apiKey: [] paths: /v1/workspace/orders/{id}: get: summary: Get an order description: >- One order (Etsy receipt) of your connected Etsy shops by its order ID: status, totals, the buyer's name, the shipping address, the buyer's and the seller's messages, the gift message, every item (with the listing image), the shipments and the refunds, as Alura last stored them from Etsy. An address Etsy withholds (Preferred Partner regions) is `null` with `shipping_address_error: etsy_restricted`, and an order of only digital items has none (`no_physical_items`). `expand=payment` adds Etsy's payment: gross, fees and net (null with `payment_error: not_fetched` when Alura has not stored it). The other `expand=` values are for MCP clients, which get messages and the address only when they ask; over REST these are always included. Holds buyer personal data, as Etsy provides it. An order outside the workspace is 404. Needs the `orders:read` scope and the Customer analytics workspace permission. Costs 1 API credit per call, expansions included. Cost: 1 API credit per call. operationId: workspace.orders.get parameters: - name: id in: path required: true schema: description: >- The Etsy order (receipt) ID. An order outside the workspace is 404. type: string pattern: ^[0-9]{1,20}$ example: '3456789012' - name: fields in: query required: false description: >- Comma-separated dotted paths to return; `id`, `object` and `as_of` always come back. schema: type: string - name: expand in: query required: false description: >- Comma-separated related objects to include: `payment`, `shipping_address`, `message_from_buyer`, `message_from_seller`, `gift_message`. Free. schema: type: string responses: '200': description: OK headers: Request-Id: $ref: '#/components/headers/Request-Id' Alura-Credits-Cost: $ref: '#/components/headers/Alura-Credits-Cost' Alura-Credits-Remaining: $ref: '#/components/headers/Alura-Credits-Remaining' content: application/json: schema: type: object properties: object: type: string const: workspace.order id: type: string description: The Etsy receipt ID. shop_id: type: string description: The connected shop the order belongs to. status: description: >- Etsy's receipt status, snake_case: `paid`, `completed`, `open`, `payment_processing`, `canceled`, `fully_refunded`, `partially_refunded`. New values may be added. type: - string - 'null' paid: type: - boolean - 'null' shipped: type: - boolean - 'null' delivered: type: - boolean - 'null' created_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' buyer: type: object properties: id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' description: The Etsy buyer's user ID; null for a guest checkout. name: description: The name on the order, as Etsy gives it. type: - string - 'null' required: - id - name additionalProperties: false description: Who placed the order. item_count: anyOf: - type: integer - type: 'null' description: >- Units ordered (the sum of the items' quantities); null when Alura has not stored the items. grand_total: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' description: What the buyer paid in total (`totals.grand_total`). as_of: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When the shop's orders were last synced from Etsy; null when never. updated_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' fetched_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When Alura last fetched this order from Etsy (order webhooks refresh one order at a time); null while Alura records no per-order time (today always). shipping_address: x-alura-expansion: shipping_address description: >- Null with `shipping_address_error` when there is none. Always present over REST; over MCP only with `expand=shipping_address`. anyOf: - type: object properties: name: type: - string - 'null' line1: type: - string - 'null' line2: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' zip: type: - string - 'null' country: description: ISO 3166-1 alpha-2 country code. type: - string - 'null' formatted: description: The whole address as Etsy formats it for a label. type: - string - 'null' required: - name - line1 - line2 - city - state - zip - country - formatted additionalProperties: false description: >- Where the order ships. A part Etsy did not give is null, never an empty string. - type: 'null' shipping_address_error: x-alura-expansion: shipping_address description: >- Why `shipping_address` is null: `etsy_restricted` (Etsy withholds the address in Preferred Partner regions), `no_physical_items` (only digital items), `not_fetched` (Alura has not stored the items); null with an address. Always present over REST; over MCP only with `expand=shipping_address`. anyOf: - type: string enum: - etsy_restricted - no_physical_items - not_fetched - type: 'null' is_gift: type: - boolean - 'null' gift_message: x-alura-expansion: gift_message description: >- The buyer's gift note. Always present over REST; over MCP only with `expand=gift_message`. type: - string - 'null' message_from_buyer: x-alura-expansion: message_from_buyer description: >- The buyer's note to the seller. Always present over REST; over MCP only with `expand=message_from_buyer`. type: - string - 'null' message_from_seller: x-alura-expansion: message_from_seller description: >- The seller's note to the buyer. Always present over REST; over MCP only with `expand=message_from_seller`. type: - string - 'null' payment_method: description: Etsy's payment method code, for example `cc` or `pp`. type: - string - 'null' totals: type: object properties: subtotal: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' shipping: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' tax: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' vat: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' discount: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' gift_wrap: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' grand_total: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' required: - subtotal - shipping - tax - vat - discount - gift_wrap - grand_total additionalProperties: false description: >- Etsy's receipt totals; a total of 0 (no tax, no discount) is a real 0. items: type: array items: type: object properties: id: type: string description: The Etsy transaction ID. listing_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' title: description: The listing title when the buyer ordered. type: - string - 'null' quantity: anyOf: - type: integer - type: 'null' sku: type: - string - 'null' price: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' description: The price of one unit. shipping_cost: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' variations: anyOf: - type: array items: type: object properties: name: type: string value: type: string required: - name - value additionalProperties: false - type: 'null' description: >- The variation values the buyer chose; null while Alura stores none for the item (today always). is_digital: type: - boolean - 'null' image_url: description: >- The listing image Etsy shows for the item, 570px wide; the only field Alura adds. type: - string - 'null' paid_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' shipped_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' required: - id - listing_id - title - quantity - sku - price - shipping_cost - variations - is_digital - image_url - paid_at - shipped_at additionalProperties: false shipments: type: array items: type: object properties: carrier: description: The carrier as Etsy reported it, for example `usps`. type: - string - 'null' tracking_code: type: - string - 'null' notified_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: When Etsy notified the buyer of the shipment. required: - carrier - tracking_code - notified_at additionalProperties: false refunds: type: array items: type: object properties: amount: anyOf: - type: object properties: amount: type: string description: Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' reason: type: - string - 'null' status: description: Etsy's refund status. type: - string - 'null' created_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' required: - amount - reason - status - created_at additionalProperties: false items_omitted: type: integer minimum: 0 description: >- How many of the order's items `items` leaves out: 0 over REST (every item); over MCP, the items past the first 25 (GET /v1/workspace/orders/{id} has them all). payment: x-alura-expansion: payment description: >- With `expand=payment`: Etsy's payment for the order. null with `payment_error` when Alura has not stored it or cannot tell its currency, never zeros. anyOf: - type: object properties: gross: anyOf: - type: object properties: amount: type: string description: >- Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' description: What the buyer paid. fees: anyOf: - type: object properties: amount: type: string description: >- Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' description: Etsy's payment processing fees. net: anyOf: - type: object properties: amount: type: string description: >- Decimal string in the order's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same amount in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- An amount of the order; null when Alura has not stored it. - type: 'null' description: What the shop received. required: - gross - fees - net additionalProperties: false - type: 'null' payment_error: x-alura-expansion: payment description: >- With `expand=payment`, why `payment` is null: `not_fetched` (Alura has not stored the payment), `currency_unknown` (the payment's or the order's currency is not stored), `currency_unverified` (the payment's currency differs from the order's, so its amounts' currency is not certain), `amount_unreadable` (no amount of it can be read). null when `payment` is present. anyOf: - type: string enum: - not_fetched - currency_unknown - currency_unverified - amount_unreadable - type: 'null' required: - object - id - shop_id - status - paid - shipped - delivered - created_at - buyer - item_count - grand_total - as_of - updated_at - fetched_at - is_gift - payment_method - totals - items - shipments - refunds - items_omitted additionalProperties: false example: object: workspace.order id: '3456789012' shop_id: '22841907' status: completed paid: true shipped: true delivered: true created_at: '2026-10-02T14:20:00.000Z' buyer: id: '12345' name: Jane Doe item_count: 2 grand_total: amount: '44.46' currency: USD usd: '44.46' as_of: '2026-10-08T06:00:00.000Z' updated_at: '2026-10-06T09:00:00.000Z' fetched_at: null shipping_address: name: Jane Doe line1: 1 Example Street line2: null city: Springfield state: IL zip: '62701' country: US formatted: |- Jane Doe 1 Example Street Springfield, IL 62701 United States shipping_address_error: null is_gift: true gift_message: Happy birthday, Sam! message_from_buyer: Please write "Sam" on the mug. message_from_seller: null payment_method: cc totals: subtotal: amount: '37.00' currency: USD usd: '37.00' shipping: amount: '4.50' currency: USD usd: '4.50' tax: amount: '2.96' currency: USD usd: '2.96' vat: amount: '0.00' currency: USD usd: '0.00' discount: amount: '0.00' currency: USD usd: '0.00' gift_wrap: amount: '0.00' currency: USD usd: '0.00' grand_total: amount: '44.46' currency: USD usd: '44.46' items: - id: '41001' listing_id: '1834720561' title: >- Personalized name mug, custom coffee mug with name, 11oz ceramic gift quantity: 2 sku: MUG-11-WHITE price: amount: '18.50' currency: USD usd: '18.50' shipping_cost: amount: '4.50' currency: USD usd: '4.50' variations: null is_digital: false image_url: >- https://i.etsystatic.com/22841907/r/il/a1b2c3/5001/il_570xN.5001_mug1.jpg paid_at: '2026-10-02T14:21:00.000Z' shipped_at: '2026-10-04T10:00:00.000Z' shipments: - carrier: usps tracking_code: EZ1000000001US notified_at: '2026-10-04T10:00:00.000Z' refunds: [] items_omitted: 0 '400': $ref: '#/components/responses/Problem400' '401': $ref: '#/components/responses/Problem401' '402': $ref: '#/components/responses/Problem402' '403': $ref: '#/components/responses/Problem403' '404': $ref: '#/components/responses/Problem404' '405': $ref: '#/components/responses/Problem405' '429': $ref: '#/components/responses/Problem429' '500': $ref: '#/components/responses/Problem500' '503': $ref: '#/components/responses/Problem503' x-codeSamples: - lang: bash label: cURL source: |- curl "https://api.alura.io/v1/workspace/orders/3456789012" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/orders/3456789012', { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}`, }, }); console.log(await res.json()); - lang: python label: Python source: |- import json import os import urllib.request request = urllib.request.Request( "https://api.alura.io/v1/workspace/orders/3456789012", headers={ "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}", }, ) with urllib.request.urlopen(request) as response: print(json.load(response)) components: headers: Request-Id: description: '`req_` + ULID; quote it when reporting a problem.' schema: type: string Alura-Credits-Cost: description: API credits this call cost. schema: type: integer Alura-Credits-Remaining: description: >- API credits left in the workspace's monthly allowance, counting calls still in flight. Absent when it cannot be read right now. schema: type: integer responses: Problem400: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/invalid_request title: Invalid request status: 400 code: invalid_request detail: Invalid request suggestion: Fix the request as the detail says, then send it again. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem401: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/unauthorized title: Unauthorized status: 401 code: unauthorized detail: Unauthorized suggestion: 'Send a valid API key as `Authorization: Bearer alura_sk_...`.' retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem402: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_exhausted title: API credits exhausted status: 402 code: credits_exhausted detail: API credits exhausted suggestion: Upgrade the plan or wait for the monthly reset. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem403: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/plan_required title: Plan required status: 403 code: plan_required detail: Plan required suggestion: Upgrade the workspace plan to use this operation. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem404: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/not_found title: Not found status: 404 code: not_found detail: Not found suggestion: Check the ID, or search for it first. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem405: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/method_not_allowed title: Method not allowed status: 405 code: method_not_allowed detail: Method not allowed suggestion: Use one of the methods in the Allow header. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem429: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/rate_limited title: Rate limited status: 429 code: rate_limited detail: Rate limited suggestion: Wait for Retry-After, then retry. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem500: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/internal_error title: Internal error status: 500 code: internal_error detail: Internal error suggestion: Retry; if it keeps failing, report the request_id. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem503: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_unavailable title: API credits unavailable status: 503 code: credits_unavailable detail: API credits unavailable suggestion: Retry shortly. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B schemas: Problem: type: object description: RFC 9457 problem details. properties: type: type: string format: uri title: type: string status: type: integer code: type: string description: A code from the error catalog; new codes may be added. x-extensible-enum: - invalid_request - unknown_parameter - invalid_cursor - cursor_window_exceeded - invalid_reference - id_type_mismatch - invalid_keyword - shop_id_required - sales_window_not_covered - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - browser_refused - role_required - impersonation_refused - recent_sign_in_required - etsy_scope_required - etsy_partner_required - not_found - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - reconnect_required - listing_busy - shop_create_busy - idempotency_partial_unverifiable - activation_skipped - idempotency_processing - unprocessable - listing_removed_on_etsy - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - sync_cooldown - shop_write_budget_exhausted - internal_error - write_misconfigured - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - create_lock_unavailable - etsy_capacity - upstream_timeout detail: type: string suggestion: type: string retryable: type: boolean request_id: type: string upgrade_url: type: string format: uri description: 'credits_exhausted and plan_required: where to upgrade the plan.' credits_needed: type: integer description: 'API credit refusals: what the call needed.' credits_remaining: type: integer description: >- API credit refusals: what is left (of the month, or of the day for daily_credit_cap_exceeded). resets_at: type: string format: date-time description: >- credits_exhausted and daily_credit_cap_exceeded: when the limit resets. required: - type - title - status - code - detail - suggestion - retryable - request_id securitySchemes: apiKey: type: http scheme: bearer description: 'An API key: `Authorization: Bearer alura_sk_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.