The v4 API

Send paid orders to current FetchApp (v4) from your own checkout or a Stripe webhook. Create a key, retry safely, check delivery, resend and expire.

Selling through something FetchApp does not connect to directly, such as Stripe Checkout, your own cart or an automation tool? A developer can send each paid order to FetchApp with the v4 API. FetchApp then gives your customer their files, links and license keys, and emails them a download link, just as it does for an order you create under Orders → New order.

If you sell on Shopify or PayPal, you do not need any code: start with the quickstart. The rest of this guide is for the developer building your connection.

Which API your account uses

Check the address you use to sign in to FetchApp:

  • https://<handle>.fetchapp.app: your account is on current FetchApp (v4). Use this guide.
  • https://<handle>.fetchapp.com: your account uses the v3 API, which keeps working for it.

Your handle is your account’s name at the start of that address. Credentials for the v3 API do not work with the v4 API. If you are unsure which applies, contact support with your account address.

Every route, field, response and error is listed in the interactive API reference.

Before you start

  1. A Business plan. The API is part of the Business plan; see pricing. On other plans, requests are refused with 403 plan_required.
  2. A key with the order permissions. In your FetchApp admin, open API keys. Under Create a key, name the key, tick orders:write (create orders, resend their email, end their access) and orders:read (look orders up), then choose Create key. The order permissions start unticked, so an existing key usually lacks them: create a new key for your order code.
  3. Keep the key on your server. FetchApp shows it once. Store it with your server’s other secrets, never in a web page, browser code or an app.
  4. A SKU on every product you sell. A SKU is the product code that matches each order line to a FetchApp product. Send it exactly as it appears on the product, including capitals. You can send FetchApp’s product id instead.

Your API address and key

Every account uses the same address. Your key tells FetchApp which account a request is for. Send it in the Authorization header of every request:

https://app.fetchapp.app/api/v4
Authorization: Bearer fa4_…

Paths in this guide follow that address, so GET /orders means GET https://app.fetchapp.app/api/v4/orders.

Creating an order

When your checkout confirms a payment, send the order. This example reads the key from an environment variable, FETCHAPP_API_KEY:

curl -X POST https://app.fetchapp.app/api/v4/orders \
  -H "Authorization: Bearer $FETCHAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "reference": "INV-1042",
        "buyer_email": "[email protected]",
        "buyer_name": "Ann Example",
        "lines": [{"sku": "EBOOK-01", "quantity": 1}]
      }'
Field What to send
reference Required. Your own order or payment id, such as an invoice number or a Stripe Checkout Session id. It becomes the order’s name in FetchApp and makes retries safe.
buyer_email Required. One address; the download email goes there.
buyer_name Optional.
lines Required. Each line names a product by sku or product_id, with a quantity (1 if you leave it out). Each unit gets its own downloads and license key.
send_email Optional, true unless you send false. With false, the order is created without emailing your customer; a resend sends the email later.

You can also give one order a lower download limit or an earlier expiry than the product’s; the reference explains how. Fields FetchApp does not recognise are refused with 422 invalid, so a misspelt option never changes what happens.

A new order answers 201 Created with the order and "created": true. FetchApp delivers it like an order you create by hand: download limits and expiry come from the product or your account settings, license keys come from the product’s pool, and the email goes out within a minute or so. The answer includes download_url, your customer’s download page. Anyone with that link can download the order, so show it only to that customer, for example on your thank-you page.

Retries are safe

Send the same order again, with the same reference, buyer email and lines, and FetchApp answers 200 with the order it already made and "created": false. Nothing is created twice and your customer gets one email. If a request times out, or your payment provider notifies you twice, send the order again.

Use a reference that belongs to one payment, such as your order number or payment id. A reference already used by a different order (another buyer email or other lines) is refused with 409 reference_taken, and the existing order stays as it is. Orders entered in the admin and imported from a CSV share the same references.

When a product is not found

Every line must match a product, or nothing is created. If a SKU is unknown, a product is archived, or a quantity is too high, FetchApp answers 422 invalid_lines and lists every line that needs fixing, with its position in your request (index, counting from 0) and a code such as unknown_sku. Your customer receives nothing until the whole order goes through, so an order is never half delivered.

Fix the product in FetchApp, or the SKU in your store, then send the same order again with the same reference.

Other answers to plan for:

Answer What to do
401 Check the key is complete and has not been revoked or expired.
403 plan_required The account needs a Business plan.
403 insufficient_scope The key lacks a permission. Create a key with the order permissions.
422 invalid error.field names the first field to fix.
429 rate_limited Wait for the seconds in the retry-after header, then try again.
5xx Try again later with the same request. The reference keeps it safe.

Checking an order and its email

Look an order up by FetchApp’s id or by your reference (percent-encoded, so INV/42 becomes INV%2F42):

GET /orders/INV-1042

GET /orders lists your orders from every source, newest first; the reference explains paging and filters. Each line has a delivery status: delivered means your customer can download it now, and not_delivered means the product had nothing to deliver (no file, link or license key) when the order arrived.

email.status says where the download email is:

Status What it means
queued, sending On its way, usually within a minute or so.
sent, delivered Accepted by the email provider; in your customer’s mailbox.
held Your account has reached its email allowance for now. FetchApp keeps the email and sends it later by itself. Share the download_url with your customer meanwhile.
bounced Your customer’s mailbox refused it. Give them the download_url another way.
failed The email provider rejected it. A resend tries again.
skipped A send check stopped it, and reason says why: for example, buyer emails are turned off in your settings.

The reference lists every status and reason.

Email volume. Orders you create with the API send delivery emails like any other order, and count towards your account’s email allowance. New accounts start with a lower allowance. Before a launch or a large batch of orders, contact support so we can check your account. See limits.

Resending the email

POST /orders/INV-1042/resend

FetchApp queues the email again and answers 202, the same as Resend email on the order’s page in your admin, with the same send checks and email allowance. It also sends the first email of an order created with send_email: false. If the email cannot be resent, the answer is 409 resend_refused with a reason; for bounced, give your customer the download_url another way.

Ending access after a refund

POST /orders/INV-1042/expire

This ends your customer’s access to everything in the order straight away, and sends no email. It is safe to repeat. Use it after a refund or a chargeback. To give access back, open the order in your admin and use Reopen access.

Recipe: Stripe Checkout

FetchApp has no Stripe connection of its own. A small webhook on your server, written by you or your developer, passes each paid Checkout Session to FetchApp.

Set up once

  1. In Stripe, give each Product a metadata key fetchapp_sku, with the SKU of the matching FetchApp product as its value.
  2. In FetchApp, create a key with orders:write and store it on your server.
  3. In Stripe, add a webhook endpoint on your server for checkout.session.completed, and for checkout.session.async_payment_succeeded if you accept payment methods that settle later.

When a payment arrives, check Stripe’s signature, continue only when the session’s payment_status is paid or no_payment_required (or the event is checkout.session.async_payment_succeeded), and create the order in FetchApp:

FetchApp field From Stripe
reference The Checkout Session id (cs_live_…)
buyer_email The session’s customer_details.email
buyer_name The session’s customer_details.name
lines One per line item: sku from its product’s fetchapp_sku, and its quantity

Then answer Stripe. After 200 or 201, reply with success. After 429 or a 5xx, reply with an error so Stripe tries again; the session id makes that safe. After 409 or 422, nothing was created: reply with success, alert yourself, fix the SKU or product, and resend the event from the Stripe dashboard.

Because the reference is the session id, repeated webhooks and the two events of a delayed payment make one order and one email. For refunds, listen for charge.refunded, look up the Checkout Session for the charge’s payment intent, and expire the order by its session id.

Products, files and uploads

The same API and keys also manage your products, files and uploads, with the products and files permissions on a key. The interactive API reference documents those routes.

Moving code from the v3 API

If your code calls the v3 API and your account is now on current FetchApp (v4):

  • Create a v4 key. v3 credentials do not work here.
  • Send the order fields at the top level of the request. reference takes the place of vendor_id, and each line carries a quantity instead of one item per unit.
  • send_email is true unless you send false. Send false to keep v3’s default of no email.
  • An unknown SKU refuses the whole order and lists the line. The v3 API skips that line and delivers the rest.

Help with your connection

Contact support with your account address, the request you sent and the response you received. Leave your API key out of the message. We can help you find the right part of the reference and check your account setup.

Last verified 2026-11-17

Something wrong on this page?