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
-
A Business plan. The API is part of the Business plan; see pricing.
On other plans, requests are refused with
403 plan_required. -
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) andorders: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. - 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.
- 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
-
In Stripe, give each Product a metadata key
fetchapp_sku, with the SKU of the matching FetchApp product as its value. -
In FetchApp, create a key with
orders:writeand store it on your server. -
In Stripe, add a webhook endpoint on your server for
checkout.session.completed, and forcheckout.session.async_payment_succeededif 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.
referencetakes the place ofvendor_id, and each line carries aquantityinstead of one item per unit. -
send_emailistrueunless you sendfalse. Sendfalseto 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.