Skip to content
YoPrintDevelopers

Export purchase orders in a date range to CSV

Open .md

POST/v1/api/store/{team_slug}/data_export/export_purchase_order_list

v1Operation ID v1_public_data_export_export_purchase_order_list

Starts a CSV export of purchase orders whose issue date falls in the range, one row per purchase order, with the vendor, status, ordered and received totals, and the related sales orders and customers. Deleted purchase orders are left out. It runs in the background: the response is the new export with status pending.

Permission

Any member of the team. Exports do not check the role: every member can export every type, including sales orders, invoices, payments and tax, even a member whose role can't see them in the web app.

Business rules

  • start_date and end_date are required, and end_date can't be before start_date. There is no maximum range. There is no date_field: the range is the purchase order's issue date.
  • One export of each type at a time for the whole team: while one is pending or generating, creating another of the same type is a 422 (duplicate_report).
  • At most 3 exports pending or generating per team, of any type. A fourth is a 429 (export_capacity).
  • columns, when sent, must be a non-empty list of column ids for this type. GET /v1/api/store/{team_slug}/data_export/definitions lists them with their labels.
  • idempotency_key, when sent, must be a string of at most 100 characters. Reusing a key with a different type, different settings or another person is a 422.

Side effects

  • Queues the export and returns it at once with status pending. The file is built in the background.
  • People with the Download Center open see it appear and update live. No email is sent.
  • The file is kept for 3 days after it is ready, then deleted. The export stays in the list as history.

Path parameters

  • team_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team

Request body

application/json, required.

  • end_datestring (date-time)required

    End of the range, inclusive, on or after start_date. A date alone means midnight UTC at its start, which leaves that day out, so send the last moment of the day: 2026-10-31T23:59:59.999Z.

  • start_datestring (date-time)required

    Start of the range, inclusive: a date and time in UTC, such as 2026-10-01T00:00:00Z. An offset (2026-10-01T00:00:00-07:00) is accepted and converted to UTC; a value with neither is read as UTC.

  • columnsarray of strings

    The columns to include, in the order you want them in the file. Omit it for every column in the default order. Repeats are dropped.

    • Each item is one of: "id", "name", "vendor", "issue_date", "due_date", "billing_address_label", "warehouse_label", "creator", "status", "received_subtotal", "received_tax", "received_total", "ordered_subtotal", "ordered_tax", "ordered_total", "related_orders", "related_customers", "internal_note", "vendor_note"
    • At least 1 item
    • Items must be unique
  • idempotency_keystring

    Optional, a string of up to 100 characters. Send the same key to retry the same request safely: you get the export it created, and nothing new starts while that export is pending, generating, ready, or failed with export_generation_failed. If it failed with export_queue_failed or export_attempt_expired, the same key queues it again. Keys are shared by the whole team.

    • At most 100 characters

Response

200Successful response.

  • dataobjectrequired
    Child fields (12)
    • configobject | nullrequired

      What you asked for: the dates (and date_field) as you sent them, and the columns you chose, without repeats, with schema_version. Null for customer and product exports sent without columns.

      Child fields (5)
    • created_atstring (date-time)required
    • created_byinteger | nullrequired

      A plain number for the person who created it. It is not a hash id and no operation takes it; show creator.name instead.

    • creatorobject | nullrequired

      The person who created it; null if their account was deleted. More of their account fields may appear; rely only on these.

      Child fields (3)
      • emailstring
      • idinteger

        The same plain number as created_by, not a hash id.

      • namestring
    • error_codestring | nullrequired

      Why it failed. export_generation_failed: the file could not be built; create a new export. export_attempt_expired: it did not finish in time. export_queue_failed: it could not be queued. Null unless status is failed.

      • One of: "export_generation_failed", "export_attempt_expired", "export_queue_failed"
    • expires_atstring (date-time) | nullrequired

      When the download stops working: 3 days after the export became ready. The file is then deleted; the export stays in the list but can't be downloaded.

    • file_sizeinteger | nullrequired

      File size in bytes, once ready.

    • idstringrequired

      The export id. Use it to poll and to download.

    • progressobjectrequired
      Child fields (2)
      • completedintegerrequired

        Rows written so far, not counting the header row. Updated every 500 rows; product exports update only at the end.

      • totalinteger | nullrequired

        Rows in the file, not counting the header row. Null until the export is ready: there is no total to show a percentage against while it runs.

    • statusstringrequired

      pending: queued. generating: running. ready: the file can be downloaded. failed: see error_code.

      • One of: "pending", "generating", "ready", "failed"
    • typestringrequired
      • One of: "customer_list", "sales_order_list", "invoice_list", "invoice_item_list", "payment_list", "purchase_order_list", "tax_list", "simple_product_list", "variant_product_list"
    • updated_atstring (date-time)required
  • statusintegerrequired
  • successbooleanrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

  • 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

  • 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

    When
    Dates are missing, not dates, or out of order, or, for sales orders, date_field is missing or not one of the six (invalid_export_request, "Choose valid, ordered export dates and a supported date field.").
    Fix
    Send both dates, with end_date on or after start_date, and for sales orders a date_field from the list.
    When
    A column id is unknown, columns is not a list, or it is empty (invalid_export_request, "The selected export columns are invalid." or "Select at least one export column.").
    Fix
    Use ids from the definitions operation, or omit columns.
    When
    idempotency_key is not a string or is longer than 100 characters (invalid_export_request, "The export request key is invalid.").
    Fix
    Send a string of up to 100 characters, or leave it out.
    When
    An export of this type is already pending or generating for your team (duplicate_report, "There is already a report being generated. Please wait until the report is fully generated").
    Fix
    Poll the running export and download it instead, or wait until it finishes.
    When
    The idempotency_key was used for a different export, or by another member (invalid_export_request, "This request key was already used for a different export.").
    Fix
    Use a new key for a new export.

  • 429Your team already has 3 exports pending or generating.

    When
    Three exports are already pending or generating (export_capacity).
    Fix
    Wait for one to finish, then try again.

  • 503Exports are paused for a few minutes during a YoPrint update, or the export could not be queued (export_queue_failed, "The export could not be queued. Try again.").

    When
    Exports are paused during an update (export_creation_paused, with Retry-After: 120), even for a retry with the same key; or the export could not be queued (export_queue_failed, no Retry-After).
    Fix
    When paused, wait the Retry-After seconds and send the request again. After a queue failure, send it again with the same idempotency_key to queue the same export.

Notes

  • The range is inclusive at both ends and is compared in UTC, with times. To cover whole days in your team's time zone, convert its midnights to UTC, or send the offset: 2026-10-01T00:00:00-07:00 to 2026-10-31T23:59:59.999-07:00. There is no maximum range.
  • Amounts in the file are decimal strings with 2 decimal places and no currency symbol, such as 125.00. In invoice and tax exports (invoice_list, tax_list), tax_percentage is a percentage as a decimal string (8.25, 0), empty when the invoice has no single tax rate (for example a fixed tax amount). In sales order, invoice, and tax exports (sales_order_list, invoice_list, tax_list), the paid column is TRUE or FALSE.
  • Dates in the file are YYYY-MM-DD, in your team's time zone.
  • The full flow: create the export, poll GET /v1/api/store/{team_slug}/data_export/{id} every few seconds until status is ready (or failed), then download the file with GET /v1/api/store/{team_slug}/data_export/{id}/download within 3 days.
  • Retrying with the same idempotency_key returns the same export and starts nothing new while it is pending, generating, ready, or failed with export_generation_failed (send a new key to try that one again). After export_queue_failed or export_attempt_expired, the same key queues the same export again, and the one-per-type (422 duplicate_report) and three-per-team (429 export_capacity) limits apply.
  • The file is CSV, UTF-8 with a byte order mark. Its first row holds the column ids, such as order_id (not the labels), in the order of columns or, without it, the default order. An export with no matching records has only that row.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com