# Fulfillbot Docs

All pages of https://docs.rephut.com in one file, in the order of the site navigation: the home page, Help, then Developers. The API's base URL is https://api.rephut.com/v1.

---

Source: https://docs.rephut.com/

# Fulfillbot Docs

Guides and reference for working with Fulfillbot.

## Help

For store owners: create your account, top up your wallet, buy products and manage your stock ([How sourcing works](https://docs.rephut.com/sourcing)), place and follow dropship orders, ship stock in bulk, and connect your Shopify or WooCommerce store. Start here: [Get started](https://docs.rephut.com/start).

## Developers

Build on the Fulfillbot API: every endpoint with examples, errors, rate limits and webhooks. Start with the overview: [Fulfillbot API](https://docs.rephut.com/developers).

---

Source: https://docs.rephut.com/start

# Get started

Fulfillbot buys products for you, keeps them in our warehouse, and packs and ships your orders to your customers. This page takes you from a new account to your first order.

## Create your account

1. Open the [sign-up page](https://app.rephut.com/signup).
2. Enter your work email and a password of at least 10 characters. Your company name, your name, your country and the other business details are optional.
3. Click **Create account**.

If the page also shows **Continue with Google**, you can use your Google account instead. Google must have verified the email address.

There is no approval step: your account works as soon as it's created. What you see next depends on whether we need to verify your email:

- "Check your inbox": we've emailed you a link. Open it, click **Verify my email**, then sign in. The link works for 24 hours. If the email doesn't arrive, click "Didn't get it? Resend" to get a new link.
- "Your account is ready": you can sign in straight away.

Until your email is verified, signing in says "Please verify your email first. Check your inbox for the link we sent." A link that was already used or is too old shows "This link is invalid or has expired": request a new one.

## Your first sign-in

The first time you sign in, a welcome page asks a few questions about your business. Everything on it is optional: click **Save and continue**, or **Skip for now** to go straight to the portal. You can fill in this page only once, and you don't see it if you already gave your company or business details when you signed up. To change your company details later, ask your account manager.

If your account manager created your account or reset your password, you get a temporary password. The first time you sign in with it, you choose your own password before you can go on.

If you started from our Shopify app, you go on to link your store after signing in. See [Install the Shopify app](https://docs.rephut.com/shopify/install).

## The home page

The portal opens on **Home**:

- **Needs your attention** lists everything waiting for you: orders to fix, orders waiting for payment, quotes to review, unpaid purchase orders and more. The same list is in the **To do** tab of the bell at the top. See [Your account](https://docs.rephut.com/start/account#notifications-and-to-do).
- The wallet card shows what you can spend, with **Top up wallet**. See [Your wallet](https://docs.rephut.com/wallet).
- Below that are how your recent orders shipped, how far your requests, quotes, purchase orders and orders have got, and your recent activity.
- On the side are a quick shipping estimate and your account manager's contact details.

![The portal home page with the things that need you, the wallet card and the quick shipping estimate](https://docs.rephut.com/images/portal-home.png)

## Your first steps

1. Top up your wallet. Purchase orders, shipping and handling are paid from it. See [Top up your wallet](https://docs.rephut.com/wallet/top-up).
2. Get your products into **My products**. You can only order products that are in My products: products you found with **Search** and added, and products from quotes you accepted after a request under **Requests**. See [How sourcing works](https://docs.rephut.com/sourcing).
3. Set your shipping preferences, so each order gets the shipping option you want for its destination. See [Your account](https://docs.rephut.com/start/account#shipping-preferences).
4. Choose how orders reach us: connect your Shopify or WooCommerce store ([Connect your store](https://docs.rephut.com/stores)), or create orders yourself or import them from a Shopify file ([Place an order](https://docs.rephut.com/orders/place)).
5. Follow your orders under **Orders**. See [Dropship orders](https://docs.rephut.com/orders).

If you get stuck, contact your account manager.

---

Source: https://docs.rephut.com/start/account

# Your account

Signing in, passwords, the notification bell, and the settings that affect your orders.

## Sign in

Sign in with your email and password, or with **Continue with Google** if the sign-in page shows it. Messages you may see:

- "Incorrect email or password."
- "Please verify your email first. Check your inbox for the link we sent." See [Get started](https://docs.rephut.com/start#create-your-account).
- "This account is not active. Please contact us."
- "This is a staff account. Please sign in on the staff workspace."

If you signed up with a password and later click **Continue with Google** with the same email, we link your Google account to your portal account. For your security we then remove your password and sign you out on your other devices: from then on, sign in with Google, or set a password again (see below). If we can't link them, you see "We couldn't connect Google to the existing account for this email. Sign in with your email and password instead."

## Forgotten password

1. On the sign-in page, click **Forgot password?**.
2. Enter your email and click **Send reset link**. The page says "If that email is registered, we've sent a reset link."
3. Open the link in the email. It works once, for 1 hour.
4. Choose a new password and click **Update password**.

You're then signed out on all your devices, and sign in again with the new password. If the sign-in page doesn't offer **Forgot password?**, ask your account manager to reset your password.

## Change your password

Open **Settings** and click **Change password** under your email; the account menu at the top right has it too. Enter your current password and the new one, then click **Update password**. You stay signed in here; your other devices are signed out.

If you have no password, because you signed up with Google or linked Google to your account, you see **Set a password** instead:

- if we can email you, click **Email me a link** and choose your password from the email;
- otherwise, if you signed in more than 10 minutes ago, you're asked to sign in with Google again first, and then have 10 minutes to set it.

## Notifications and to do

The bell at the top of every page has two tabs:

- **Notifications**: updates about your account, for example a quote that's ready, an order that needs payment to ship or has shipped, a top-up we received or didn't accept, a refund, or a store you need to reconnect. The bell shows how many you haven't read. Click one to open it, or click **Mark all as read**. The **Notifications** page lists them all; we keep them for 90 days.
- **To do**: what's waiting for you right now, the same list as **Needs your attention** on **Home**. An item goes away once you've dealt with it. A top-up we didn't accept stays for 30 days, and a request we cancelled stays for a limited time.

When an order needs payment to ship, and when we release its stock because the payment didn't come in time, we usually also email you.

## Shipping preferences

**Shipping preferences** in **Settings** tells us which shipping option to use for each destination:

1. Choose a destination, or leave **All destinations (default)** to set your default.
2. Choose a shipping option and click **Save preference**. Saving a destination that already has a preference replaces it.

When we choose the shipping option for an order, we use your preference for its country. If you have none for that country, we use your default, as long as it can ship that order. If neither applies, the order waits for you as **Choose a shipping option**. The details are in [Shipping and tracking](https://docs.rephut.com/orders/shipping#how-the-shipping-option-is-chosen).

Changes apply to orders created or changed after you save. To apply them to orders that are already on hold, click **Recheck on-hold orders**, in **Settings** or on the **Needs attention** tab of **Orders**. Orders with nothing left to fix then go ahead.

## Other settings

- Company details: **Settings** shows your company name and country. To change them, ask your account manager.
- Auto purchase: at set times each day we buy what your orders waiting for stock are missing, in a purchase order paid from your wallet. It has its own card in **Settings**. See [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase).
- API access: if we've turned on API access for you, **Settings** links to your API keys. See [Fulfillbot API](https://docs.rephut.com/developers).

## If your account is on hold

If we put your account on hold, every page shows "Your account is on hold. You can view your data and top up, but new orders and requests are paused." Actions that are paused say "Your account is on hold. Please contact your account manager." Please contact your account manager.

---

Source: https://docs.rephut.com/wallet

# Your wallet

Most of what you pay us comes out of your wallet: purchase orders, shipping and handling for your dropship orders, and shipments of your stock. This page explains the figures and the two tables on the **Wallet** page. To add money, see [Top up your wallet](https://docs.rephut.com/wallet/top-up); for when each charge happens, see [When you're charged](https://docs.rephut.com/wallet/charges).

Wallet amounts are in US dollars.

## Your balance

The **Balance** card on the **Wallet** page, and the wallet card on **Home**, show:

| | What it is |
|---|---|
| **Available to spend** | "Balance plus credit limit, minus shipping set aside". This is what you can pay with right now. |
| **Wallet balance** | Your top-ups, minus everything we've charged, plus refunds. |
| **Credit limit** | How far below zero your balance may go. It's zero unless we've agreed a credit limit with you. A **Surcharge** can still take your balance below it. |
| **Held for shipping** | "Estimated shipping for orders we're packing": money set aside for your orders, see below. |

## Money held for shipping

The only money we hold is the shipping we set aside for dropship orders.

When we reserve stock for an order, we set aside its estimated shipping plus our handling fee. The order's page shows this as **Shipping set aside**: "We've set this aside from your wallet for the estimated shipping and handling of this order. When we weigh the parcel we take the actual charge and release the rest."

We release the amount set aside for an order when:

- we weigh the parcel and take the actual charge;
- the order is cancelled;
- we have to pack the order again;
- we release the order's stock because its shipping charge wasn't paid in time (see [When you're charged](https://docs.rephut.com/wallet/charges#unpaid-shipping-charges)).

While an order is **Awaiting payment**, its amount stays set aside.

We set the money aside even when your wallet can't cover it, so **Available to spend** can go below zero. **Wallet** and **Home** then show how much you're short of the shipping set aside. Top up at least that much so we can ship those orders without delay.

## Your top-ups

**Your top-ups** lists every top-up, newest first: the day you paid, the method, the amount you paid (for another currency, also its value in US dollars), the fee, the amount we credited, the status and your proof. Top-ups your account manager records for you are listed too.

| Status | What it means |
|---|---|
| **Pending confirmation** | We haven't checked the payment yet. Your balance doesn't change until we have. |
| **Credited** | We've added it to your balance. |
| **Not accepted** | We didn't accept it. The reason is shown under the status. |
| **Reversed** | We credited it and later took it back out. **Wallet activity** shows this as **Top-up void**. |

## Wallet activity

**Wallet activity** lists every change to your balance, newest first: the date, the type, the order, purchase order or shipment it belongs to (for a top-up, its payment method), the amount and your balance after it.

| Type | What it is |
|---|---|
| **Top-up** | A top-up we credited. |
| **Goods payment** | A purchase order paid from your wallet. |
| **Goods refund** | Money back for a purchase order. |
| **Shipping** and **Handling fee** | What we charge for a dropship order when we weigh the parcel. |
| **Surcharge** | Extra shipping after the carrier billed a higher weight than we charged. |
| **Shipping refund** and **Handling refund** | Money back for an order we cancelled after weighing it, or had to pack again. When we weigh a parcel again and its shipping costs less, the difference is a **Shipping refund** too. |
| **Shipment payment** and **Shipment refund** | Payments and refunds for shipments of your stock. |
| **Adjustment** | A correction by our team, with its reason. |
| **Top-up void**, **Refund reversal**, **Surcharge reversal** and **Shipment refund reversal** | An earlier entry taken back. |

Both tables show 50 rows a page. For a statement of any period, see [When you're charged](https://docs.rephut.com/wallet/charges#statements).

---

Source: https://docs.rephut.com/wallet/top-up

# Top up your wallet

You pay us with one of the payment methods on the **Wallet** page, then tell us about the payment. We check it and add it to your wallet.

## Choose how to pay

On **Wallet**, go to **Top up your wallet** and choose a **Payment method**. We set up the methods and the currencies you can pay in:

- A method such as a bank transfer or Wise can have an account for each currency. **Currency** picks the account: the form starts with the account for your country, otherwise our default account.
- A method without accounts shows how to pay with it, and you pay in US dollars.

If the form says top-ups aren't available, please contact your account manager.

## Pay to the account shown

**Pay to this account** shows the details of the account for the currency you chose, and each row has a copy button. The last row, **Reference**, is your payment reference. It's the same for every top-up: "Please include the reference so we can find your payment."

Pay from your bank or your Wise account, in the account's currency. If the account shows a note below its details, follow it too.

![The Wallet page with the top-up form, demo account details and the Your top-ups table](https://docs.rephut.com/images/wallet-top-up.png)

## Tell us about the payment

1. In **Amount you paid**, enter what you paid, in the currency shown next to it.
2. In **Date paid**, enter the day you paid. It can't be in the future.
3. Under **Payment proof**, add a screenshot or PDF of the payment: JPG, PNG, WebP or PDF, up to 5 MB.
4. Add a note if you want to, then click **Submit top-up**.

Each proof can be used for one top-up only. If that top-up is **Not accepted** or **Reversed**, you can use its proof again. If you submit a proof that's already used for a pending or credited top-up, the form says "This payment proof has already been used for another top-up. Please upload the proof for this payment." You can have up to 5 top-ups waiting for confirmation at a time, and upload up to 20 proofs a day.

## The estimate

Before you submit, the form estimates what we'll credit:

- for an account in another currency, the value in US dollars at the account's reference exchange rate. We update these rates automatically, normally once a day;
- the fee for the payment method, if it has one;
- the estimated credit: the value in US dollars minus the fee.

It's an estimate only. When we credit the top-up, we confirm the amount in US dollars and the fee, so what we credit can differ.

## After you submit

The top-up appears under **Your top-ups** as **Pending confirmation**. Your balance doesn't change yet, so you can't pay with it until we've checked it.

When we've checked the payment, its status changes and you get a notification:

- **Credited**: the amount is in your balance. Purchase orders that auto purchase created and that are waiting for payment are paid from it straight away, as far as it covers them (see [When you're charged](https://docs.rephut.com/wallet/charges#purchase-orders)).
- **Not accepted**: the reason is shown under the status, and the top-up stays on your **To do** list for 30 days.

You can top up even while your account is on hold.

---

Source: https://docs.rephut.com/wallet/charges

# When you're charged

This page explains when money leaves your wallet and when it comes back. What you pay depends on your own prices and shipping rates: **Shipping rates** in the portal shows your shipping rates ([Shipping rates](https://docs.rephut.com/shipments/rates)), and **Statements** gives you a record of every charge.

## Purchase orders

A purchase order is what we buy for you. Its page shows what's still due. To pay it from your wallet, use the pay button on the purchase order and confirm. "Pays the full amount due. Your available balance includes any credit limit on your account." If your wallet doesn't have enough, top up first. The payment shows in **Wallet activity** as **Goods payment**. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#pay-a-purchase-order).

If we've agreed another way to pay with you, we record your payment on the purchase order instead.

When some items of a dropship order aren't in your stock, we may buy them for you: we pay that purchase order from your wallet when we place it, so keep enough in your wallet for orders that are **Waiting for stock**.

Purchase orders that auto purchase creates are paid from your wallet straight away if **Available to spend** covers them. Otherwise they wait for payment, and we pay them as soon as a top-up is credited that covers them. If one is still unpaid when its payment deadline passes, we cancel it and pause auto purchase. See [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase).

## Shipments of your stock

When a shipment of your stock is waiting for payment, we can take its payment from your wallet; it shows in **Wallet activity** as **Shipment payment**. If we've agreed another way to pay, we record your payment on the shipment instead. See [Ship your stock](https://docs.rephut.com/shipments#pay-for-a-shipment).

## Dropship orders

For every dropship order you pay shipping and our handling fee. Money moves at three moments:

1. When we reserve stock for the order, we set aside the estimated shipping and handling, shown on the order as **Shipping set aside**. Nothing is charged yet. The new order form shows this amount before you place an order.
2. When we weigh the packed parcel, we charge shipping for its actual weight and size, with the order's shipping option at your rates (or the option we switch to if it can't take the parcel, see [Shipping and tracking](https://docs.rephut.com/orders/shipping#how-the-shipping-option-is-chosen)), plus the handling fee, and release the amount set aside. The order becomes **Ready to ship**. Its **Fulfilment** card shows **Shipping charged** and the total, and **Wallet activity** shows **Shipping** and **Handling fee**. If we weigh the parcel again before it ships, we charge or refund only the difference.
3. After the parcel has shipped, if the carrier bills us for a higher weight than we charged, we charge the difference as **Surcharge**.

## Awaiting payment

When we weigh a parcel and your wallet can't cover its shipping and handling, we don't take the charge. The parcel stays packed and the order shows **Awaiting payment**: "We've packed and weighed this parcel, but your wallet doesn't cover the shipping charge yet. Top up your wallet and we'll take the charge and ship it. To change the order, contact your account manager."

For this check we count **Available to spend** plus the amount already set aside for this order. The order's **Shipping payment due** card shows the weight we recorded, the estimated charge and how much to top up. "This is an estimate from the weight we recorded. We take the charge from your wallet just before we ship, so it can change slightly if shipping rates change before then."

You get a notification and an email. Top up, and once your top-up is credited, we take the charge just before we ship the parcel. A credited top-up first pays any auto purchase orders that are waiting for payment, oldest first, so top up enough to cover both. Meanwhile the amount set aside for the order stays set aside.

![An order awaiting payment with its Shipping payment due card](https://docs.rephut.com/images/order-awaiting-payment.png)

## Unpaid shipping charges

If an order stays **Awaiting payment** for too long, we release the stock we were holding for it, and the amount set aside. We decide how long that is, and the email we send then tells you. The order isn't cancelled. It stays under **Needs attention**, still shows **Awaiting payment**, and says: "We released the stock we were holding for this order because its shipping charge wasn't paid in time. The order hasn't been cancelled. Top up your wallet and contact your account manager when you're ready, and we'll check stock and pack it again."

## Refunds

Refunds go back to your wallet:

- If we cancel a dropship order after weighing it, or have to pack it again, we refund its shipping and handling as **Shipping refund** and **Handling refund**.
- If a purchase order is cancelled, or ends up costing less than you paid (for example because some goods didn't arrive), we return the difference as **Goods refund**.

## Statements

**Statements** downloads an account statement for any period of up to 366 days, as a PDF or an Excel file: choose the dates or a quick range, then click **Download PDF** or **Download Excel**. A statement shows your opening balance, every top-up, charge and refund, your purchase orders and your closing balance. "Statement dates follow China Standard Time (GMT+8)."

![The Statements page with the date fields and the PDF and Excel buttons](https://docs.rephut.com/images/statements-page.png)

---

Source: https://docs.rephut.com/sourcing

# How sourcing works

Fulfillbot buys products for you from our suppliers in China. The goods come to our warehouse, we check them, and they become your stock, ready for your dropship orders and shipments. This page shows the ways to buy and where each one leads.

## Ways to buy

| Way | Use it when | What happens |
|---|---|---|
| **Search** and the cart | You can find the product yourself among our suppliers' products. | You order from your cart and get a purchase order straight away: the suppliers' prices plus their shipping to our warehouse and our service fee, in US dollars at the exchange rate when you order. See [Search and the cart](https://docs.rephut.com/sourcing/search). |
| Sourcing request | You can't find the product, or you'd like us to find a supplier for it from a link or photos. | We look for suppliers and send you a quote. See [Sourcing and reorder requests](https://docs.rephut.com/sourcing/requests) and [Quotes](https://docs.rephut.com/sourcing/quotes). |
| Reorder request | You want more of products you already have agreed prices for. | Your account manager creates a purchase order at your agreed prices. See [Sourcing and reorder requests](https://docs.rephut.com/sourcing/requests#reorder-request). |
| Auto purchase | Your dropship orders are waiting for stock. | At set times each day we buy what those orders are missing. See [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase). |

Prices on **Search** are our suppliers' prices in Chinese yuan, with an approximate value in US dollars. Quotes and purchase orders are in US dollars.

## From purchase order to stock

1. A purchase order lists what we buy for you and what it costs. You find it under **Purchase orders**. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders).
2. You pay it from your wallet, or in another way agreed with your account manager. Some purchase orders are paid from your wallet automatically. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#pay-a-purchase-order).
3. We order the goods from the suppliers, and they ship them to our warehouse in China.
4. At the warehouse we count, check and weigh every delivery. The purchase order shows what we found, with photos. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#warehouse-inspection).
5. The good pieces are added to your stock under **Inventory**, ready for your dropship orders and for shipments to your own warehouse or to Amazon FBA. See [Inventory](https://docs.rephut.com/products/inventory) and [Ship your stock](https://docs.rephut.com/shipments).

## Your products

What you order from **Search**, what you add there to **My products**, and the products of quotes you accept all appear in **My products**. That's where you add your own SKUs so that your orders find the right product. See [My products](https://docs.rephut.com/products).

---

Source: https://docs.rephut.com/sourcing/search

# Search and the cart

**Search** finds products from our suppliers in China. You choose options and quantities, put them in your cart, and order them in one go. Your order becomes a purchase order that you pay from your wallet.

## Search for products

Type what you're looking for in the box on the **Search** page, or in the search box at the top of every page, and press Enter. You can search in English or in Chinese. If you have a link to a product of one of our suppliers, paste it into the box to open that product directly; a link we don't recognise is searched as words.

Each result shows the product's photo, title and price, how many have sold and where it ships from, and for some products how often buyers ordered again. Sort the results by **Best match**, **Most sold** or price. To filter by a price range, or by the smallest quantity the supplier sells, fill in the fields and click **Apply**. **Load more** at the bottom shows more results.

Titles and options are translated automatically, so the wording can be rough, and some text, for example inside product photos, may still be in Chinese.

If searching isn't possible at the moment, the page says "Search isn't available right now. Please try again in a few minutes." If you search a lot in a short time, it says "You've searched a lot in a short time. Please wait a little and try again." Opening products and your cart counts too.

![The Search results page with made-up demo products](https://docs.rephut.com/images/search-results.png)

## Search by image

On the **Search** page, click the camera button (**Search by image**) and choose or drop a photo under **Search with a photo**, or paste an image anywhere on the page. The photo can be a JPG, PNG or WebP file of up to 5 MB. Results start sorted by **Most similar**, and the filters aren't available.

You can search with up to 50 images a day (days follow China Standard Time). **Find by image** on your store's products counts towards this too: see [Link your store products](https://docs.rephut.com/stores/products#find-or-source-a-product-you-don-t-have-yet). When you reach the limit, the upload says "You've reached today's upload limit. Please try again tomorrow."

## The product page

Click a result to open the product. The page shows its photos, specifications and description, where it ships from, how many have sold, and the smallest total quantity the supplier sells.

If the price depends on the quantity, a strip shows the price for each quantity range. The range is set by your total quantity across all the options you choose, and that price applies to each of them.

Enter a quantity for each option you want in the table. Each row shows the option's unit price, with an approximate value in US dollars, and how many the supplier has in stock, from the latest information we have. The bar at the bottom adds up your options and pieces, and shows the total in Chinese yuan and an approximate US dollar total that includes our service fee. Shipping from the supplier to our warehouse is worked out in your cart.

- **Add to cart** puts these quantities in your cart. It works once your total for the product reaches the supplier's smallest quantity. If an option is already in your cart, its quantity goes up.
- **Add to My products** adds the options you tick to **My products** without ordering them, so you can add your own SKUs, link your store products or turn on auto purchase. You can add up to 50 options at a time. Once every option is in My products, the button reads **In My products**.

![A product page with its options, quantities and the Add to cart bar](https://docs.rephut.com/images/search-product.png)

## Prices

Prices on **Search** are our suppliers' prices in Chinese yuan (RMB). The approximate US dollar values (≈) use our current exchange rate and are rounded up; the results page shows the rate. When you order, we add each supplier's shipping to our warehouse and our service fee, and the exchange rate is fixed on the purchase order.

International shipping from our warehouse isn't included. It's charged later, when the goods leave: with each dropship order, or with a shipment of your stock.

## The cart

The **Cart** button at the top of every page shows what's in your cart. **View cart** opens the cart page, and **Checkout** opens it at the order summary.

The cart groups items by supplier. Suppliers are named Supplier A, Supplier B and so on, with the city they ship from. Each supplier ships to our warehouse separately, so each has its own **Shipping to our warehouse**, marked:

- **Calculated**: worked out from the supplier's shipping rates;
- **Estimate**: we couldn't get the supplier's rate for all of these items, so a standard amount is included.

Tick the items you want to order, or **Select all**. Items you don't tick stay in your cart and don't count towards the total. Change a quantity or remove an item on its row; a quantity of zero removes it.

Each time you open the cart, we check every item against the latest information we have. A row tells you if its price went up or down since you added it, if the supplier has fewer in stock than you want, or if it's no longer available.

Your cart holds up to 100 options from up to 20 different products, with a quantity of up to 100,000 on each. When it's full, adding says "Your cart is full. Remove some items before adding more." Items stay in your cart until you order or remove them.

![The cart with one supplier, its shipping to our warehouse and the order summary](https://docs.rephut.com/images/search-cart.png)

## Order from the cart

1. Tick the items to order. The **Order summary** shows the products, the shipping to our warehouse for the suppliers of the ticked items, our service fee, the total in Chinese yuan and **You pay in USD**: the amount of your purchase order.
2. If you want, write a **Note for our team (optional)**, for example about colours or packing.
3. Click **Place order**. The button shows the amount in US dollars.

"Placing an order creates a purchase order awaiting payment for this USD amount; you can pay it from your wallet right away." All the ticked items, from every supplier, go into one purchase order, and they leave your cart.

You can't order while a ticked item needs attention (it's no longer available, the supplier has too few in stock, or the product is below the supplier's smallest quantity): fix it or untick it. If prices, shipping or the exchange rate changed since you opened the cart, the order isn't placed and the cart says "Prices, shipping or stock changed since you opened your cart. We've updated it. Check the new total and place the order again."

## After you order

You go straight to the new purchase order. It's marked **Placed via Search** and says "Order placed. Pay below and we'll start buying from the suppliers."

Nothing is charged until you pay. Pay from your wallet under **Pay from your wallet** and confirm with **Confirm payment**, or pay as shown under **How to pay**. A purchase order from the cart has no payment deadline. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#pay-a-purchase-order).

The products you ordered are added to **My products**. After you've paid, we buy from the suppliers, the goods come to our warehouse, and we check them in to your stock. Follow it on the purchase order: see [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders).

If your account is on hold, you can still search, but adding to the cart and ordering say "Your account is on hold. Please contact your account manager."

---

Source: https://docs.rephut.com/sourcing/requests

# Sourcing and reorder requests

A request asks us to do something for you: find suppliers for new products (a sourcing request), or buy more of products you already have agreed prices for (a reorder). Your requests are under **Requests**; start one with **New request**.

## Sourcing request

Use a sourcing request for products you can't find on **Search**, or when you'd rather we found the supplier.

1. On **Requests**, click **New request**, then **Start a sourcing request** under **Source new products**.
2. Fill in the request details:
   - **Destination country**: where the goods go in the end.
   - **What are the goods for?**: **Dropshipping stock**, **Ship to me** or **Amazon FBA**.
   - **Needed by** and **Notes**, if you want.
3. For each product, enter the **Product name** and the **Quantity**, and give us either a **Product link** (from any website) or photos under **Photos**. You can also describe the specifications, such as colour, size, material or packaging, and add a **Target unit price (USD)** if you have one in mind.
4. Click **Add another product** for each further product, then **Submit request**.

Limits:

- up to 20 products in one request, with a quantity of up to 1,000,000 each, and product names of up to 200 characters;
- up to 5 photos for each product, as JPG, PNG or WebP files of up to 5 MB each;
- up to 100 photo uploads a day (days follow China Standard Time).

You can also start a sourcing request from **Ask us to source it** on your store's products ([Link your store products](https://docs.rephut.com/stores/products#find-or-source-a-product-you-don-t-have-yet)), on **SKUs to map** in **Orders**, and on **Needs your decision** ([Product decisions](https://docs.rephut.com/products/decisions)). The form is then filled in for you.

## Request statuses

| Status | What it means |
|---|---|
| **Submitted** | We've received your request. You can still withdraw it. |
| **In progress** | Our team is working on it. Your account manager may write to you on the request, under **Message from your account manager**. |
| **Quoted** | Your quote is ready: the request shows **Your quote is ready**, and **Review quote** opens it. See [Quotes](https://docs.rephut.com/sourcing/quotes). |
| **Completed** | You accepted the quote, or, for a reorder, we've created the purchase order. |
| **Cancelled** | You withdrew the request, or we cancelled it and the request shows why. |

![The Requests page with requests in different statuses](https://docs.rephut.com/images/requests-list.png)

When you decline a quote, or it expires before you decide, the request goes back to **In progress**. When we send a quote, you get a notification. If we cancel a request, it stays on your **To do** list for 30 days.

## Reorder request

A reorder buys more of products you have agreed prices for: the prices of quotes you accepted.

1. On **Requests**, click **New request**, then **Start a reorder** under **Reorder my products**. You can also tick products in **My products** and click **Reorder selected** (see [My products](https://docs.rephut.com/products#buy-again)).
2. Enter the quantity you need of each product. The table shows each product's agreed unit price, how many you have in our warehouse, and the subtotal.
3. Choose **What are the goods for?**, add notes if you want, and click **Submit reorder**.

A reorder can have up to 20 products. Products from **Search** without an agreed price aren't listed: add them to your cart from Search or from **My products** instead.

There's no quote for a reorder. Your account manager creates a purchase order at your agreed prices, and the request becomes **Completed** and links to it. Pay it as described in [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#pay-a-purchase-order).

## Withdraw a request

"Changed your mind? You can withdraw this request until we start working on it." While a request is **Submitted**, open it and click **Withdraw request**; it becomes **Cancelled**.

Once we've started on it, the portal says "This request is already being handled, so it can't be withdrawn. Please contact your account manager." In that case, contact your account manager.

While your account is on hold, you can't send new requests.

---

Source: https://docs.rephut.com/sourcing/quotes

# Quotes

A quote is our reply to a sourcing request: the products we found, their prices for your quantities, and the ways we can ship them. Your quotes are under **Quotes**. A quote that's waiting for you also shows under **Needs your attention** on **Home** and in your **To do** list, and you get a notification when we send it.

## Your quotes

**Your quotes** lists each quote with the day we issued it, **Valid until**, how many products it has, the goods subtotal and its status:

| Status | What it means |
|---|---|
| **Awaiting your decision** | Accept or decline it before it expires. |
| **Being updated** | Your account manager is preparing a new version. You can't decide on this one. |
| **Replaced by a newer version** | We've sent a newer version; the quote links to it. |
| **Accepted** | You accepted it. |
| **Declined** | You declined it. |
| **Expired** | It wasn't accepted or declined in time. |

## Read a quote

A quote shows:

- the day we issued it, **Valid until**, the destination and our notes;
- each product with our SKU, your SKU if you gave one, the quantity, the unit price and the amount, and the goods subtotal;
- **Shipping options**: the ways we can ship the goods to the destination, with the transit time, the shipping cost and the total with the goods. Where the price depends on the postcode, it's shown as a range.

Amounts are in US dollars. A quote is valid until the end of its **Valid until** day, China Standard Time (GMT+8).

![A quote with its products, shipping options and the accept and decline buttons](https://docs.rephut.com/images/quote-detail.png)

## Accept a quote

Under **Your decision**, click **Accept quote**. Accepting:

- accepts the whole quote;
- makes its prices your agreed prices: each product goes into **My products** at this price, replacing any earlier agreed price for it, and you can reorder it later (see [Sourcing and reorder requests](https://docs.rephut.com/sourcing/requests#reorder-request));
- marks the request **Completed**.

Accepting doesn't charge your wallet and doesn't place an order by itself. Your account manager then creates a purchase order for the goods. It appears under **Purchase orders** and in your **To do** list, and you pay it there: see [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#pay-a-purchase-order).

## Decline a quote

Tell us what should change in **What should we change? (optional)**, and click **Decline quote**. Your feedback stays on the quote, the request goes back to **In progress**, and your account manager can send you a new version.

## Expired and updated quotes

You can only decide on the latest version of a quote, while it's **Awaiting your decision**. Otherwise the page says "This quote can no longer be accepted or declined. It may have expired or been updated. Please refresh the page."

An expired quote can't be accepted. If you still want the goods, ask your account manager for a new version: contact your account manager.

---

Source: https://docs.rephut.com/sourcing/purchase-orders

# Purchase orders

A purchase order is what we buy for you from our suppliers, and what you pay for it. Purchase orders come from your cart on **Search**, from quotes you accepted and from reorders, from auto purchase, and from our team when your orders wait for stock. You find them all under **Purchase orders**.

## The Purchase orders page

**Your purchase orders** shows a card for each purchase order: its number, date and status, the amount payable, paid and due, and its first products with how many are in our warehouse. **Pay now** opens a purchase order with an amount due; otherwise **View order** opens it. You can search by product name, SKU or order number.

The tabs:

| Tab | Purchase orders |
|---|---|
| **All** | Every purchase order. |
| **Awaiting payment** | Not paid in full, and we haven't started buying yet. |
| **In progress** | **Paid** and waiting to be bought, **Purchasing**, or **On the way to warehouse** or **Arrived at warehouse**. If an amount is still due, the card shows **Pay now**. |
| **Completed** | Everything is checked in or settled. Some may still have an amount due. |
| **Cancelled** | Cancelled purchase orders. |

## Statuses

| Status | What it means |
|---|---|
| **Awaiting payment** | Nothing is paid yet, and we haven't started buying. |
| **Deposit received** | Part is paid, for example a deposit agreed with your account manager, and we haven't started buying. |
| **Paid** | Paid in full. We're about to order from the suppliers. |
| **Purchasing** | We're ordering the goods from the suppliers. |
| **On the way to warehouse** | The suppliers have shipped the goods to our warehouse. |
| **Partially arrived** | Some of the deliveries have arrived. |
| **Arrived at warehouse** | All deliveries have arrived. If something was short or defective, we sort it out with you. |
| **In stock** | Everything is checked in or settled, but an amount is still due. |
| **Completed** | Everything is checked in or settled, and paid. |
| **Cancelled** | We cancelled it. |

From **Purchasing** on, the statuses show how far the purchase order has got, not whether it's paid: we can start buying before it's paid in full, for example after a deposit. Check **Amount due** on the purchase order to see what's still to pay.

Our team moves a purchase order along as the work happens; apart from paying, you don't need to do anything.

## Pay a purchase order

The **Payment** card on the purchase order shows the order total, what you've paid and the **Amount due**.

To pay from your wallet, use **Pay from your wallet** at the top of the purchase order: click the pay button, then **Confirm payment**. "Pays the full amount due. Your available balance includes any credit limit on your account." You can't pay part of the amount from your wallet. If your wallet doesn't have enough, the card says how much to top up, with **Go to wallet**. The payment shows in **Wallet activity** as **Goods payment**.

To pay another way, follow **How to pay** under **Payment**. When we receive your payment, we add it to the purchase order. If you've agreed a deposit with your account manager, the purchase order shows **Deposit received** until the rest is paid.

Some purchase orders are paid from your wallet without you doing anything:

- purchase orders our team creates for your orders that are **Waiting for stock** are paid when we create them;
- purchase orders from auto purchase are paid when we create them if **Available to spend** covers them, or otherwise when a top-up is credited. If one isn't paid by its due date, we cancel it and pause auto purchase. See [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase#paying).

Purchase orders from your cart, from quotes and from reorders aren't paid automatically, and they have no payment deadline.

**Download PI** downloads a proforma invoice of the purchase order as a PDF.

While your account is on hold, paying from your wallet says "Your account is on hold. Please contact your account manager."

## Charges for orders from the cart

A purchase order placed from your cart also has a **Charges** card: the products, each supplier's shipping to our warehouse (marked as an estimate where we used a standard amount) and our service fee. If goods turn out short, only the products are refunded; the service fee and the shipping to our warehouse are not.

## Arrival and short deliveries

The products table shows, for each product, how many we've **Ordered** from the supplier, how many good pieces are **In our warehouse**, and how many are **Short / refunded**. Deliveries can arrive in parts, and the purchase order is **Partially arrived** until all of them are in.

If a supplier sends fewer pieces than ordered, or some are defective, our team agrees with you what to do: wait for the rest, refund the missing pieces, or accept fewer. Pieces you accept as short or that we refund lower the amount payable.

## Warehouse inspection

"We count every delivery at our warehouse, check it for defects and weigh it. Defective pieces aren't added to your stock."

The **Warehouse inspection** card shows each check-in: the date, how many pieces were received, good and defective, the unit weight of each product, any note from us, and photos. Click a photo to see it larger, and use the arrow keys to move between photos. The card appears as soon as we've checked a delivery in, and you get a notification, also when we find defective or missing pieces.

The good pieces go into your stock straight away (see [Inventory](https://docs.rephut.com/products/inventory)), and orders waiting for that stock get it reserved automatically.

![A purchase order with its warehouse inspection and photos](https://docs.rephut.com/images/purchase-order-inspection.png)

## Refunds and cancelling

You can't cancel a purchase order in the portal. If you need one cancelled, contact your account manager.

When we refund a purchase order, for a cancelled order or for short-shipped goods, the money goes back to your wallet. It shows in **Wallet activity** as **Goods refund**, and on the purchase order under **Refunded to your wallet** as **Refund for cancelled order** or **Refund for short-shipped items**. Our team makes these refunds; they aren't automatic.

---

Source: https://docs.rephut.com/sourcing/auto-purchase

# Auto purchase

Auto purchase buys stock for your dropship orders that are **Waiting for stock**. It runs at set times each day and buys only what those orders are missing, for the products you turn it on for.

## What it buys

"At set times each day (Beijing time) we check your backordered orders and buy only what's missing: what the orders need, minus your free stock and what's already on the way." What's already on the way includes purchase orders that are still waiting for payment.

It only buys products you've turned it on for. In **My products**, each option has a switch in the **Auto purchase** column. You can turn it on for products with an agreed price from a quote, and for products from **Search** that are still on sale; otherwise the row says "Needs a quoted price, or a Search product that's still on sale." Products with an agreed price are bought at that price. Products from Search are bought at the supplier's current price, with the supplier's shipping to our warehouse and our service fee.

For a product from Search, **Settings** next to the switch opens **Auto purchase settings**:

- **Price rise limit (%)**: if the supplier's price has gone up by more than this since you turned it on or last accepted a new price, we hold the item for your decision. Leave it empty to use our default.
- **Max unit price (USD)**: if the price is above this, we hold the item for your decision. Leave it empty for no limit.

If a product stops being available, or its supplier stops selling it, we turn auto purchase off for it and the row says so.

## When it runs

The **Auto purchase** card in **Settings** shows the times it runs, in Beijing time (China Standard Time). Each run puts everything it buys into one purchase order.

Auto purchase doesn't run while your account is on hold.

## Your daily limit

**Daily limit (USD)** on the **Auto purchase** card sets the most auto purchase spends in a day, up to the limit we set for your account. Leave it empty to use our whole limit, and click **Save limit**.

Everything auto purchase buys in a day counts, including what you buy on **Needs your decision**. Orders are taken oldest first; those that don't fit wait for a later run. An order that costs more than your whole daily limit never fits, so it goes to **Needs your decision**, where you can buy it straight away. A daily limit of zero turns automatic buying off.

## Paying

"Everything goes into one purchase order paid from your wallet. If your wallet is short, the order waits for payment; if it isn't paid by the due date we cancel it and pause auto purchase until you top up or resume."

- If **Available to spend** covers the purchase order, we pay it from your wallet straight away.
- Otherwise it waits as **Awaiting payment**. When a top-up is credited, we pay waiting auto purchase orders from it, oldest first (see [Top up your wallet](https://docs.rephut.com/wallet/top-up#after-you-submit)). You can also pay one yourself on the purchase order (see [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#pay-a-purchase-order)).

The due date isn't shown on the purchase order. When we can email you, our email about the run gives it.

## Overdue payments and pausing

If an auto purchase order still isn't paid by its due date, we try once more to pay it from your wallet. If that doesn't work, we cancel it and pause auto purchase. Every page then shows "Auto purchase paused — top up your wallet or resume in Settings", and the **Auto purchase** card says "Auto purchase is paused because purchase order payment was overdue." with how much you need available to resume: what the purchase orders cancelled for non-payment cost, plus what the auto purchase orders waiting for payment still need.

To resume:

- top up: once a credited top-up leaves you enough available, auto purchase resumes by itself;
- or, once you have enough available, click **Resume auto purchase**.

## Items that need your decision

Auto purchase never buys more than your orders need on its own. Items below the supplier's smallest quantity, items whose price went up beyond your limits, items we can't buy and orders over your daily limit wait for you on **Needs your decision**, and every page shows a banner with how many there are. See [Product decisions](https://docs.rephut.com/products/decisions).

## Turn it off

Switch auto purchase off for a product in **My products**, or set your daily limit to zero. If we've turned it off for your account, the card says "Auto purchase is turned off for your account. Contact your account manager."

---

Source: https://docs.rephut.com/products

# My products

**My products** lists the products you can put in your dropship orders: products you added from **Search**, products you ordered from your cart, and products from quotes you accepted.

## The My products page

Products from **Search** are grouped by product: the card shows the product's title and the city its supplier ships from, with a row for each option you have, such as a colour or size. **Add more options** opens the product on Search. Each product from a quote has its own card. The newest products come first.

Each row shows:

| Column | What it shows |
|---|---|
| **Our SKU** | Our code for the product, with a button to copy it. |
| **Price** | Your agreed price, or a reference price. See below. |
| **In stock** | How many you have available in our warehouse; it links to **Inventory**. If we don't know the product's weight yet, it says "Weight to be confirmed". |
| **Auto purchase** | Whether auto purchase buys this product. See [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase). |
| **Your SKUs** | Your own SKUs for this product. See [SKU mapping](https://docs.rephut.com/products/sku-mapping). |

If you've connected a store, a row also shows the store variants linked to it, and **Store variant** links another one. See [Link your store products](https://docs.rephut.com/stores/products).

You can search by product, option, our SKU or your SKU, filter to **All products**, **Has your SKU** or **No SKU yet**, and tick **Show hidden** to include hidden products.

When SKUs from your orders don't match any of your products, the page says how many, and **Map them** opens **SKUs to map** on the **Orders** page.

![My products with a product from Search and products from a quote](https://docs.rephut.com/images/my-products.png)

## Prices

- An agreed price, in US dollars, comes from a quote you accepted. It's the price for reorders and for auto purchase.
- A product from **Search** without an agreed price shows a reference price: the supplier's price in Chinese yuan with an approximate value in US dollars, without our service fee and the supplier's shipping to our warehouse, and the day we last checked it. What you pay is worked out when you order it from your cart.
- A row with neither shows a dash.

## Hide or remove a product

The menu at the end of each row has **Hide**, or **Unhide** for a hidden product. Hidden products, marked **Hidden**, leave the list (tick **Show hidden** to see them) and the product list of the new order form, but your SKUs and store links still match them in orders. A hidden product comes back when you add it again from **Search**.

Products from **Search** can also be removed from the same menu. You can't remove a product while you have stock of it, while it's on an open purchase order or on orders that haven't shipped, or if it comes from your quotes; the dialog then lets you hide it instead. Removing a product also removes your SKUs on it.

A product we no longer offer is marked **Not available**, with the reason. You can't order it or add SKUs to it.

## Buy again

Tick the rows you want more of and click **Reorder selected**:

- products from **Search** go into your cart, ticked, with at least the supplier's smallest quantity. Finish in the cart: see [Search and the cart](https://docs.rephut.com/sourcing/search#order-from-the-cart);
- products with an agreed price open a reorder request with those products: see [Sourcing and reorder requests](https://docs.rephut.com/sourcing/requests#reorder-request).

If some of them are no longer available, the page says so.

## Product images

Each row shows the option's photo, or the product's photo. Products without a photo show a placeholder.

---

Source: https://docs.rephut.com/products/sku-mapping

# SKU mapping

Your store and your own systems know products by your SKUs. Mapping each of your SKUs to one of your products lets orders and imported files find the right product by themselves.

## Add your SKU

In **My products**, find the option's row and, under **Your SKUs**, click **Your SKU**. Type your SKU and click Add, or press Enter. While you type, the box suggests SKUs from your orders that are waiting for a product.

A product can have several of your SKUs, but each SKU belongs to one product. If the SKU is already on another product, the box asks whether to move it here; click Move to do so.

A SKU you gave us on a quote is shown as from quote and can't be removed here: it's part of your agreed prices.

To remove one of your SKUs, click the × on it. Orders that already found their product keep it; later orders with that SKU no longer match.

## What mapping does to orders

When you add a SKU, orders on hold as **SKU not mapped** because of it are updated straight away, and the message says how many now use the product and how many still need other fixes. If many orders use the SKU, the message asks you to open the rest from **Orders**; **Recheck on-hold orders** checks them again. See [Fix an order](https://docs.rephut.com/orders/problems#sku-not-mapped).

## How an order line finds its product

For each line of an order, we look for the product in this order:

1. for an order from your store, the store variant's link (see [Link your store products](https://docs.rephut.com/stores/products));
2. your SKU, mapped to one of your products here;
3. our own SKU of one of your products;
4. your SKU on your agreed prices, from a quote.

If nothing matches, the line is **SKU not mapped** and the order waits for you.

## Other places to map SKUs

- On **Orders**, the **Needs attention** tab lists **SKUs to map**: choose the product for each SKU. See [Fix an order](https://docs.rephut.com/orders/problems#sku-not-mapped).
- When you import a Shopify orders file, the preview lists **SKUs to map**, and your choices are saved as mappings. See [Place an order](https://docs.rephut.com/orders/place#import-orders-from-a-file).
- Your own system can manage mappings through the API: see [SKU mappings](https://docs.rephut.com/developers/reference/sku-mappings).

## SKUs to fix

If one of your SKUs points to a product that's no longer available or no longer in **My products**, the page shows a notice. Open it to remove that SKU or map it to another product.

---

Source: https://docs.rephut.com/products/decisions

# Product decisions

Auto purchase never buys more than your orders need on its own, and never pays more than your limits allow. When it holds an item, the item waits for you on **Needs your decision**. Every page then shows a banner with how many items need your decision and a link to the page, and you get a notification.

## What each item asks

### Below the supplier's smallest quantity

Your orders need fewer pieces than the supplier sells at once. The card lists the options and how many of each your orders need. Its buy button buys the supplier's smallest quantity now; anything your orders don't need goes into your stock. Or click **Dismiss**.

### The price went up

The card shows the old and the new price, or that the price is above your **Max unit price (USD)**.

- **Accept new price**: we buy at the new price in the next run. If the new price is above your maximum unit price, that limit is removed.
- **Turn off auto purchase**: stop auto purchase for this product.
- **Dismiss**.

### Out of stock or no longer sold

"This variant is out of stock or no longer sold." Click **Find it in Search** to look for the product elsewhere, **Turn off auto purchase**, or **Dismiss**.

### We need to quote this item

"We need to quote this item." **Ask us to source it** opens a sourcing request filled in with the product (see [Sourcing and reorder requests](https://docs.rephut.com/sourcing/requests)). Or click **Dismiss**.

### Over your daily limit

"This order costs more than your daily limit" on its own, so it never fits in a run. **Buy now** buys it straight away: "Buying now ignores your daily limit." What you buy still counts towards the day's spending. Or click **Dismiss**.

### Waiting to retry

Items under **Waiting to retry** need nothing from you: "We'll retry at the next run."

## Buying from this page

The buy buttons open a dialog with what we'll buy and at what price. When you confirm, we create a purchase order and pay it from your wallet; if your wallet is short, it waits for payment (see [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase#paying)). The dialog then shows the purchase order. If you already have enough stock by then, nothing is bought.

While auto purchase is paused, buying here says "Auto purchase is paused. Resume it in Settings first." If it's turned off for your account, buying says "Auto purchase is turned off for your account. Contact your account manager."

When your daily limit is zero, the buy buttons are off. If you set it to zero yourself, raise it in **Settings**; otherwise contact your account manager.

## Dismiss

**Dismiss** hides an item without buying anything. It comes back if what your orders need changes.

---

Source: https://docs.rephut.com/products/inventory

# Inventory

**Inventory** shows the stock we hold for you in our warehouse in China.

## Your stock

**Your stock** lists every product you have in our warehouse, have reserved or have on the way:

| Column | What it means |
|---|---|
| **In warehouse** | Pieces we hold for you, including reserved ones. |
| **Reserved** | Pieces held for your dropship orders that we're packing and for your shipments. |
| **Available** | **In warehouse** minus **Reserved**: what new orders and shipments can use. |
| **Incoming** | Pieces still to come from purchase orders from **Deposit received** on. Pieces found short or defective still count here until we've agreed with you what to do. Purchase orders with nothing paid aren't counted here, though auto purchase counts them as already on the way (see [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase#what-it-buys)). |

Rows also show our SKU, and your SKU from your quotes. Inventory doesn't list stock movements: your purchase orders, orders and shipments show what happened to the stock.

![The Inventory page with stock in the warehouse, reserved, available and incoming](https://docs.rephut.com/images/inventory.png)

## How stock arrives

1. We buy the goods on a purchase order, and the supplier ships them to our warehouse. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders).
2. We check each delivery in: we count it, check it for defects and weigh it. The purchase order shows the result and photos. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#warehouse-inspection).
3. The good pieces are added to **In warehouse**. Defective pieces aren't.
4. Orders that were **Waiting for stock** get their stock reserved automatically, and we start packing them. See [Fix an order](https://docs.rephut.com/orders/problems#waiting-for-stock).

## Where stock goes

- A dropship order reserves its stock once everything in it is available, and the stock leaves when the parcel ships. See [Shipping and tracking](https://docs.rephut.com/orders/shipping).
- A shipment reserves its stock when you submit it; the stock leaves when it ships, and is available again if the shipment is cancelled. See [Ship your stock](https://docs.rephut.com/shipments).

To use your stock, tick products in **Your stock** and click **Create order** for a parcel to one customer, or **Create shipment** for a bulk shipment to your own warehouse or to Amazon FBA. Products with nothing available can't be ticked.

---

Source: https://docs.rephut.com/orders

# Dropship orders

A dropship order is one parcel that we pack from your stock in our warehouse and ship to your customer. This page explains where orders come from and what each status means.

## Where orders come from

- Your connected store: paid orders come in by themselves. See [Store orders](https://docs.rephut.com/stores/orders).
- **New order**: you create an order yourself. See [Place an order](https://docs.rephut.com/orders/place).
- **Import orders**: you upload your Shopify orders export. See [Place an order](https://docs.rephut.com/orders/place#import-orders-from-a-file).
- The API: your own system creates orders. See [Orders](https://docs.rephut.com/developers/reference/orders).

Once an order is no longer on hold, its page shows its source: Store, Imported, or Manual for orders created in the portal or through the API.

## The Orders page

**Orders** lists your orders, newest first, with the recipient, the products, the status and the shipping cost (an estimate until we weigh the parcel). The tabs:

| Tab | Orders |
|---|---|
| **All** | Every order. |
| **Needs attention** | Orders with a problem to fix, and orders waiting for payment. |
| **In progress** | Orders on their way: ready for fulfilment, waiting for stock, being packed or ready to ship. |
| **Shipped** | Shipped orders. |
| **Cancelled** | Cancelled orders. |

You can search by order number, store order number or recipient name.

On **Needs attention**, **SKUs to map** lists the SKUs from your orders that don't match any of your products yet. Map each one once, and every waiting order with that SKU updates. See [Fix an order](https://docs.rephut.com/orders/problems#sku-not-mapped).

![The Orders page with demo orders in different statuses](https://docs.rephut.com/images/orders-list.png)

## Order statuses

| Status | What it means | What you do |
|---|---|---|
| **SKU not mapped**, **Address issue**, **No items**, **Choose a shipping option** or **Shipping option unavailable** | The order has a problem, and the status names the first one. We don't ship it until it's fixed. | Fix it: see [Fix an order](https://docs.rephut.com/orders/problems). |
| **Awaiting payment** | Your wallet didn't cover the shipping charge when we weighed the parcel. | Top up: see [When you're charged](https://docs.rephut.com/wallet/charges#awaiting-payment) (if we released its stock, see [When you're charged](https://docs.rephut.com/wallet/charges#unpaid-shipping-charges)). |
| **Ready for fulfilment** | Nothing is left to fix and the order is waiting for us to reserve its stock, for example after we had to pack it again. | Nothing. |
| **Waiting for stock** | Some items aren't in your stock yet. We pack the order once everything is in. | Keep enough in your wallet for the missing items: see [Fix an order](https://docs.rephut.com/orders/problems#waiting-for-stock). |
| **Being packed** | We've reserved the stock and set aside the shipping. | Keep enough in your wallet for the shipping charge. |
| **Ready to ship** | Packed, weighed and charged. | Nothing. |
| **Shipped** | On its way. The tracking number is on the order. | Nothing. See [Shipping and tracking](https://docs.rephut.com/orders/shipping#tracking-numbers). |
| **Fulfilled by you in your store** | Shopify only: you fulfilled the whole order in Shopify before we started packing it. | Nothing. See [Store orders](https://docs.rephut.com/stores/orders#orders-you-ship-yourself). |
| **Cancelled** | We won't ship it. | Nothing. |

If an order shows **Needs attention** as its status, it's on hold but the portal can't tell which problem it has: please contact your account manager.

Orders from a connected store can also carry a flag about a change in your store. See [Store orders](https://docs.rephut.com/stores/orders#when-the-order-changes-in-your-store).

## An order's page

Open an order to see:

- **Problems**, while the order is on hold, with the order form to fix it. See [Fix an order](https://docs.rephut.com/orders/problems#edit-an-order).
- **Progress**, once the order is no longer on hold: **Received**, **Stock reserved**, **Packed** and **Shipped**, with the date of each step. Cancelled orders and orders **Fulfilled by you in your store** have no progress.
- **Items** and **Recipient**, and details such as the store order number, the shipping option and the estimated shipping.
- **Stock for this order**, while it's **Waiting for stock**.
- **Shipping set aside**, while it's **Being packed**.
- **Shipping payment due**, while it's **Awaiting payment** (if we released its stock, see [When you're charged](https://docs.rephut.com/wallet/charges#unpaid-shipping-charges)).
- **Fulfilment**, from **Being packed** on: the **Tracking number**, the date it shipped, the weight and the charges, filled in once we weigh and ship the parcel.
- **Store**, for orders from a connected store.

---

Source: https://docs.rephut.com/orders/place

# Place an order

You can create orders yourself, one at a time or by importing a Shopify orders file. Orders from a connected store come in by themselves: see [Store orders](https://docs.rephut.com/stores/orders).

## Create an order

On **Orders**, click **New order**. The form has four parts, and **Order check** next to them checks the order as you fill it in.

### Items

Click **Add product** and pick products from **My products** ([My products](https://docs.rephut.com/products)). Each product shows how many you have available in your stock; click it again to add one more. Set the quantity on each line. An order can have up to 200 lines, with a quantity of up to 100,000 on each.

If you enter your store's SKU on a line, we remember it for that product, so later orders with that SKU match it. You can also add a line by your store's SKU only: we match it to one of your products through your SKU mappings ([SKU mapping](https://docs.rephut.com/products/sku-mapping)) or the product's own SKU, and if nothing matches, the order waits as **SKU not mapped**.

### Recipient

The recipient's name, address line 1, city and country are needed before we can ship (they're marked with *). The company, phone, email, address line 2, state or province and postal code are optional, but some shipping options need the postal code. You can save the order without the needed fields and fill them in later.

### Store order

If the order came from your store, enter its order number; leave it blank for samples and other orders of your own. You can't use the same store order number twice: "You already have an order with this store order number." You can also add a note from your buyer.

### Shipping

Once you've chosen the country and added products, **Shipping** lists the options that can ship this order, each with an estimated price and delivery time; **Cheapest** and **Fastest** mark two of them. **Use my preference**, selected at first, uses your shipping preference for that destination. If you choose an option yourself and you have no preference for that country yet, we save your choice as your preference for it.

Prices here are estimates from your products' weights. The final charge is based on the packed parcel: see [Shipping and tracking](https://docs.rephut.com/orders/shipping).

### Save the order

The button at the bottom changes with the order check:

| Button | What happens |
|---|---|
| **Save and fix later** | The order still has a problem. We save it, and it waits under **Needs attention** until you fix it. |
| **Place order** | Nothing is left to fix and there's enough stock. We reserve the stock and set aside the shipping in your wallet. |
| **Place order (waits for stock)** | Nothing is left to fix, but some items aren't in stock. The order waits as **Waiting for stock**, and we reserve the stock when it arrives. |
| **Save order** | Shown while the order check has no result yet, for example before its first check finishes. |

Once you've placed an order, you can no longer change or cancel it yourself. If you need to, contact your account manager.

![The New order form with a product, a recipient in Australia, the shipping options and the order check](https://docs.rephut.com/images/new-order-form.png)

## Import orders from a file

The portal imports Shopify's orders export, exactly as it comes out of Shopify. It doesn't take other spreadsheets: if you sell on WooCommerce, connect your store instead ([Connect WooCommerce](https://docs.rephut.com/woocommerce/connect)).

1. In Shopify, open Orders, choose Export and export the orders as a CSV file. Don't change its columns.
2. In the portal, on **Orders**, click **Import orders**. Under **Upload your Shopify orders**, choose the file and click **Preview**.
3. Check the preview:
   - **SKUs to map** lists the SKUs that don't match any of your products. Choose the product for each one: when you import, we save these to your SKU mappings and use them for later orders too.
   - The orders in the file are listed with the status and shipping each will get.
   - **Skipped orders** lists the orders we won't import, with the reason.
4. Click the import button. It says how many orders it imports.

The file can be CSV or Excel (.csv, .xlsx or .xls), up to 8 MB and 2,000 orders. You can import 20 times a day (days follow China Standard Time). The file must have all of these columns, named as Shopify names them: `Name`, `Lineitem quantity`, `Lineitem sku`, `Lineitem name`, `Shipping Name`, `Shipping Company`, `Shipping Address1`, `Shipping Address2`, `Shipping City`, `Shipping Province`, `Shipping Zip`, `Shipping Country`, `Shipping Phone`, `Email`, `Notes` and `Cancelled at`. Rows with the same `Name` are one order, and that value becomes the order's store order number. If columns are missing, the portal says "Some columns of the Shopify orders export are missing. Export your orders from Shopify again and upload the file without changing its columns."

| Skipped because | Why |
|---|---|
| **Already imported** | You already have an order with this store order number. |
| **Cancelled in your store** | The order has a cancellation date in the file. |
| **No order number** | The row has no order number. |
| **Quantity isn't a whole number** | A line's quantity isn't a whole number from 1 to 100,000. |
| **No items** | The order has no line with a SKU or a product name. |
| **Order number, SKU or item list is too long** | The order number or a SKU is too long, or the order has more than 200 lines. |

Imported orders then go ahead like orders you create: those with a problem wait under **Needs attention**, the others reserve stock or wait for it.

---

Source: https://docs.rephut.com/orders/problems

# Fix an order

An order with a problem is on hold: we don't reserve stock for it or ship it until it's fixed. Its status names the first problem, and its page lists all of them under **Problems**. All orders on hold are on the **Needs attention** tab of **Orders**.

## Problems that hold an order

### SKU not mapped

The order page says a line "isn't mapped to one of your products." Fix it in one of these ways:

- On the **Needs attention** tab, under **SKUs to map**, choose the product for the SKU. Every waiting order with that SKU updates.
- Add the SKU to the product in **My products**: see [SKU mapping](https://docs.rephut.com/products/sku-mapping).
- For an order from your store, link the store variant: see [Link your store products](https://docs.rephut.com/stores/products).
- Edit the order and choose the product for the line.

### Address issue

The order page says "Recipient name is missing.", "Address line 1 is missing.", "City is missing.", "Country is missing." or "We don't recognise the country". Edit the order and fill in the address, or choose the country from the list.

### No items

"This order has no items." Edit the order and add products, or cancel it.

### Choose a shipping option

"No shipping option has been chosen yet." Edit the order and choose a shipping option, or set a shipping preference for its destination in **Settings** and then click **Recheck on-hold orders**. See [Shipping and tracking](https://docs.rephut.com/orders/shipping#how-the-shipping-option-is-chosen).

### Shipping option unavailable

"The shipping option can't take this order", followed by the reason, for example "it doesn't ship to this country", "the parcel is too heavy" or "it needs the recipient's postcode". Edit the order and choose another option, or add the missing postal code.

When you save a SKU mapping, the waiting orders with that SKU update by themselves. After you change your shipping preferences, or if an order with a mapped SKU is still waiting, click **Recheck on-hold orders** to check the orders on hold again. Orders with nothing left to fix then go ahead.

## Edit an order

You can edit an order only while it's on hold. The order page says "Fix the problems below and save the order. Once nothing is left to fix, we reserve stock for it and it can no longer be changed here." Change what's needed and save: the button works as described in [Place an order](https://docs.rephut.com/orders/place#save-the-order), and shows **Save changes** while the order check has no result yet.

For an order from your store, you can change everything except the store order number.

Once an order is no longer on hold, you can't change it here. Until it ships, its page says "Contact your account manager to change this order." (an order that's **Awaiting payment** explains the payment instead). From then on only we can change it: contact your account manager.

## Cancel an order

While an order is on hold, you can cancel it at the bottom of its page: click **Cancel this order**, add a reason if you want to, and click **Yes, cancel the order** (or **Keep the order**). You can't undo this. For an order from your store, the order in your store isn't cancelled: see [Store orders](https://docs.rephut.com/stores/orders#cancelling).

Once an order is no longer on hold, ask us to cancel it. If we cancel an order after weighing it, we refund its shipping and handling to your wallet.

## Waiting for stock

An order waits for stock when some of its items aren't in your stock yet. Its page shows **Stock for this order**: how many of each product you ordered and how many are still missing. Below that are the purchase orders we placed for the missing items, or "We're arranging stock for this order." We pay those purchase orders from your wallet when we place them, so keep enough in it: see [When you're charged](https://docs.rephut.com/wallet/charges#purchase-orders). You follow them under **Purchase orders**: see [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders).

When everything is in your stock, we reserve the stock for the whole order and pack it, without you doing anything. You can't change or cancel the order yourself while it waits: contact your account manager.

---

Source: https://docs.rephut.com/orders/shipping

# Shipping and tracking

What happens between an order being ready and your customer getting a tracking number, and how we choose the shipping option.

## From reserved stock to shipped

The order's **Progress** card follows these steps:

1. **Received**: the order is in the portal.
2. **Stock reserved**: everything in the order is in your stock, so we reserve it and the order is **Being packed**. We set aside the estimated shipping and handling in your wallet.
3. **Packed**: we've packed and weighed the parcel and taken the shipping and handling from your wallet. The order is **Ready to ship**. If your wallet can't cover the charge, the order waits as **Awaiting payment** instead: see [When you're charged](https://docs.rephut.com/wallet/charges#awaiting-payment).
4. **Shipped**: the parcel has left our warehouse with the carrier.

![A shipped order with its progress, items and tracking number](https://docs.rephut.com/images/order-progress.png)

## How the shipping option is chosen

When an order is created or changed, it gets its shipping option in this order:

1. The option you chose yourself in the order form.
2. Otherwise your shipping preference for the order's country. We use it even if it can't take this order; the order then waits as **Shipping option unavailable**.
3. Otherwise your default preference, **All destinations (default)**, but only if it can ship this order.
4. Otherwise none: the order waits as **Choose a shipping option** until you choose an option or set a preference.

An order can also show **Assigned by our team**: we chose its shipping option for you.

Which options can ship an order depends on the destination country, the postal code for options that price by postcode zone, the type of goods and the parcel's estimated weight. We check the parcel's size when we weigh it. The order form lists only the options that can take the order. The estimate uses your products' weights; when a product's weight isn't confirmed yet, the form says "Weight is an estimate — we'll confirm it when the goods arrive."

When we weigh the parcel, we charge for its actual weight, or for its size when the option charges by size and that comes to more. Some options also charge a minimum weight or round the weight up. If the order's option can't take the parcel (for example it's too big or too heavy), we switch it to an option that can take it, and charge for that one.

Your rates for each option and destination are on **Shipping rates** in the portal: see [Shipping rates](https://docs.rephut.com/shipments/rates).

## Tracking numbers

When the parcel ships, the order's **Fulfilment** card shows the **Tracking number**, with a link to the carrier's tracking page when the carrier has one, and the date it shipped. You also get a notification; orders shipped on the same day share one.

- For orders from a connected store, we send the tracking number to your store. See [Store orders](https://docs.rephut.com/stores/orders#tracking-back-to-your-store).
- If we correct a tracking number after shipping, the order shows the new one, and for an order from a connected store we send it to your store too.
- Your own system can follow your orders through the API and webhooks: see [Webhooks](https://docs.rephut.com/developers/webhooks).

---

Source: https://docs.rephut.com/shipments

# Ship your stock

A shipment sends goods from your stock in bulk: to your own warehouse, store or customer (**Wholesale**), or to an Amazon fulfilment centre (**Amazon FBA**). To send single parcels to your customers, use dropship orders: see [Dropship orders](https://docs.rephut.com/orders).

Your shipments are under **Shipments**, including shipments our team prepares for you, once we send them to you.

## Create a shipment

1. On **Inventory**, tick the products to send and click **Create shipment**. (**New shipment** on the **Shipments** page takes you to **Inventory**.)
2. Set the quantity of each product. It starts at everything available. A shipment can have up to 200 products.
3. Choose **Wholesale** and enter the recipient and address, or **Amazon FBA** and enter the FBA warehouse code and, if you have it, the FBA Shipment ID.
4. Choose the country. The shipping options that can take the goods are listed with an estimated price and transit time, with **Cheapest** and **Fastest** marked. Choose one, or choose **Let our team choose** and tell us under **How should we ship it?** whether to send it by air, sea, express or truck. The estimates use the total weight of the products; the final freight depends on the packed boxes.
5. Add notes for us if you want, for example about labels, packing or a delivery window, and click **Submit shipment**.

"Submitting reserves this stock for the shipment. We'll pack it and send you the boxes and freight to confirm. You can cancel until then."

![The New shipment form with a product, an address in Australia and the shipping options](https://docs.rephut.com/images/new-shipment.png)

## Shipment statuses

| Status | What it means |
|---|---|
| **Preparing** | We're picking and packing the goods. You can still cancel. |
| **Awaiting your confirmation** | The boxes and charges are ready for you to check. |
| **Awaiting payment** | You confirmed, and the amount due is waiting for payment. |
| **Paid** | Paid in full. We'll ship it. |
| **Shipped** | On its way, with tracking numbers. |
| **Cancelled** | It won't be shipped. The stock it reserved is available again. |

## Confirm the freight quote

When the goods are packed and weighed, we send you the shipment to confirm, and you get a notification. Its page shows:

- **Boxes**: each box with its size, weight and contents, and the total and chargeable weight;
- **Charges**: the freight, and any fees such as customs declaration, customs clearance, duty prepayment or labeling;
- **Payment**: the total, what's paid and the amount due.

Under **Your decision**, click **Confirm shipment** if everything looks right. If something should change, write it under **Feedback** and click **Send feedback**: your account manager updates the shipment and sends it to you again. If we change a shipment after you confirmed it, we ask you to confirm it again.

Unless our team prices it by hand, the freight is worked out from the packed boxes: each box's actual weight, or its volumetric weight when that's more and the shipping option charges by size, at your rates for the shipping option.

## Pay for a shipment

After you confirm, the shipment is **Awaiting payment**, or **Paid** if there's nothing to pay. There's no pay button on the shipment: pay as shown under **How to pay**, or ask your account manager to take the payment from your wallet, where it shows as **Shipment payment**. Once the amount due is paid, the shipment is **Paid** and we ship it.

## Tracking

When the shipment leaves, it becomes **Shipped**, its details show the **Tracking numbers**, and you get a notification.

Your own system can create and follow shipments, and confirm freight quotes, through the API: see [Shipments](https://docs.rephut.com/developers/reference/shipments).

## Cancel a shipment

While a shipment you created is **Preparing**, you can cancel it at the bottom of its page with **Cancel shipment**; the stock is available again. Once we've sent you the freight quote, the portal says "This shipment can no longer be cancelled here because we've already sent you the freight quote. Please contact your account manager." In that case, contact your account manager.

---

Source: https://docs.rephut.com/shipments/rates

# Shipping rates

**Shipping rates** in the portal estimates what a dropship parcel costs to ship from our warehouse to your customer, at your rates. Prices are in US dollars. Bulk shipments of your stock are priced from their packed boxes instead: see [Ship your stock](https://docs.rephut.com/shipments#confirm-the-freight-quote).

## Get an estimate

Under **Estimate shipping**, fill in:

- **Destination country**;
- **Postcode (optional)**: for countries where the price depends on the postcode, it gives you an exact price;
- **Weight (kg)**: the packed parcel's weight, up to 1,000 kg;
- **Type of goods**: **General goods**, **Contains battery** or **Sensitive goods**;
- the length, width and height of the packed parcel, if you want the estimate to include volumetric weight (each up to 1,000 cm).

Then click **Get estimates**.

## Read the estimates

**Estimates** lists every shipping option that can take the parcel, with its price, transit time and **Chargeable weight**; **Cheapest** and **Fastest** mark two of them. "These prices are estimates. The final shipping charge is based on the packed weight and size of your parcel."

- Without a postcode, an option that prices by postcode shows a range: "Price varies by postcode. Enter a postcode for an exact price."
- With a postcode it doesn't cover, an option says "This postcode is not covered by this service."
- If no option fits, the page says "We don't have a shipping option for this destination, weight and type of goods. Please contact your account manager."

## Use an option for your orders

In the **For your orders** column, an option's button saves it as your shipping preference for that country, and new dropship orders to that country use it. The option you've chosen is marked as your choice. You can change it any time in **Settings**: see [Your account](https://docs.rephut.com/start/account#shipping-preferences).

## What changes the final charge

The estimate uses what you entered. The charge for an order is worked out when we weigh the packed parcel (see [Shipping and tracking](https://docs.rephut.com/orders/shipping#how-the-shipping-option-is-chosen)):

- Weight: we charge for the parcel's actual weight, or its volumetric weight (from its length, width and height) when the option charges by size and that's more.
- Minimum weight and rounding: some options charge a minimum weight, and weights are rounded up to the option's weight step.
- Fixed fee: some options add a fixed amount per parcel, which the estimate includes.
- Postcode: some options price by postcode zone, and some don't cover every postcode.
- Type of goods and size: an option only takes the types of goods and parcel sizes it accepts. If it can't take the parcel, we switch to one that can.
- Handling: each dropship order also has our handling fee, which isn't on this page.
- After shipping: if the carrier bills us for a higher weight, we charge the difference as a **Surcharge**.

For how and when each charge is taken, see [When you're charged](https://docs.rephut.com/wallet/charges#dropship-orders).

---

Source: https://docs.rephut.com/stores

# Connect your store

Connect your Shopify or WooCommerce store to Fulfillbot and you no longer export and import order files. Paid orders from your store come in by themselves, we send tracking numbers back to the store when we ship, and your store's products link to the products we fulfil for you.

![The Stores page in the portal with a WooCommerce store and a Shopify store connected](https://docs.rephut.com/images/stores-page.png)

## What a connection does

- Paid orders from your store appear under **Orders** in the portal, with your store's order number. See [Store orders](https://docs.rephut.com/stores/orders).
- When we ship an order, we send the carrier and tracking number back to your store.
- Your store's products and variants are listed in the portal, so you can link each one to one of your products in **My products** ([My products](https://docs.rephut.com/products)). Linked products match store orders automatically. See [Link your store products](https://docs.rephut.com/stores/products).
- When an order changes in your store (cancelled, new address, different items), we update the order in the portal or flag it for you.

Orders you create in the portal or import from a file work as before.

## Shopify or WooCommerce

| | Shopify | WooCommerce |
|---|---|---|
| How you connect | Install our Shopify app, Fulfillbot-Dropship & Branding, then link it to your portal account | Click **Connect WooCommerce** on the **Stores** page, then authorize in WooCommerce or enter API keys |
| Orders we import | Paid or Partially refunded, and Unfulfilled | Status Processing |
| New orders arrive | Straight away: real-time updates are always on | Straight away when real-time updates are on, otherwise when you click **Sync now** |
| Tracking in your store | A fulfilment with the carrier, tracking number and tracking link | Through the Shipment Tracking or Advanced Shipment Tracking plugin if you have one, otherwise as an order note your customer can see; the order is then marked Completed |
| Orders you ship yourself | Fulfil the whole order in Shopify: if we haven't started packing, we close the order; otherwise we flag it | WooCommerce doesn't tell us. See [Store orders](https://docs.rephut.com/stores/orders#orders-you-ship-yourself) |
| Reconnecting | Open the app in your Shopify admin | **Reconnect in WooCommerce** or **Save keys** on the store's card |
| Removing | Uninstall the app in Shopify, or **Disconnect** in the portal | **Disconnect** in the portal |

## One store, one account

A store can be connected to one portal account only. If you try to connect a store that is already connected to another account, the portal says "This store is already connected to another account." If it's your store, contact your account manager.

You can connect several stores to one account, Shopify and WooCommerce together.

## The store's card

Each connected store has a card on the **Stores** page with:

- its status: **Connected**, or **Reconnect needed** when the store stopped accepting our access;
- when it last synced, and when the last real-time update arrived;
- a **Products** block: how many store variants there are and how many aren't linked yet, with **Manage products** (it appears after the first product sync) and **Sync products**;
- **Sync now**, which fetches orders straight away, and **Disconnect**.

Above the cards, **Orders to review** lists store orders we held back because you already have an order with the same number. See [Store orders](https://docs.rephut.com/stores/orders#orders-to-review).

## Next steps

- [Install the Shopify app](https://docs.rephut.com/shopify/install)
- [Connect WooCommerce](https://docs.rephut.com/woocommerce/connect)
- [Link your store products](https://docs.rephut.com/stores/products)
- [Stores FAQ](https://docs.rephut.com/stores/faq)

---

Source: https://docs.rephut.com/shopify/install

# Install the Shopify app

Shopify stores connect through our Shopify app, Fulfillbot-Dropship & Branding. You install it in your Shopify admin, then link it to your Fulfillbot portal account. You can't connect a Shopify store by typing its address in the portal.

## Before you start

- You need permission to install apps in your Shopify store.
- Have your portal sign-in ready. If you don't have an account yet, you can create one while linking.

## 1. Install the app

1. Find Fulfillbot-Dropship & Branding in the Shopify App Store and install it. If the **Stores** page in the portal shows **Connect Shopify**, that button opens the same listing.
2. Shopify asks you to approve the app's access: it reads your products and orders, and creates fulfilments with tracking for the orders we ship.
3. Shopify then opens the app's page in your Shopify admin.

## 2. Link the app to your portal account

1. On the app's page, click **Link to portal**. The portal opens in a new browser tab.
2. Sign in to the portal. If you don't have an account yet, create one from the sign-in page. After you verify your email and sign in in the same browser, the portal takes you back to the linking page.
3. The **Connect Shopify store** page shows which store you're connecting and to which company. Read the warning, then tick the box that confirms you just clicked **Link to portal** in your own Shopify admin.
4. Choose **Import orders from**: **New orders only**, **Last 24 hours**, **Last 7 days** or **Last 30 days**. Orders created in that period that are paid and not fulfilled yet are imported straight away.
5. Click **Confirm**. The **Stores** page opens with your Shopify store on it, and we fetch your orders in the background.
6. Go back to the Shopify tab and reload the app's page. It now shows the company the store is linked to.

![The Connect Shopify store page in the portal, with the warning, the confirmation box and Import orders from](https://docs.rephut.com/images/shopify-link-confirm.png)

The link from **Link to portal** works for 30 minutes. If it has expired, the portal says "This link has expired": go back to the app in Shopify and click **Link to portal** again. **Not now** cancels the linking.

Only confirm a link you started yourself. If someone sent you a linking page, choose **Not now**: confirming would send their store's orders into your account.

## 3. Link your products

Linking the store doesn't link your products. On the **Stores** page, click **Sync products** on your Shopify store's card, then **Manage products** to link each variant to one of your products. See [Link your store products](https://docs.rephut.com/stores/products).

## The app's page in Shopify

Once the store is linked, the app's page in your Shopify admin shows:

- the company the store is linked to, and the masked email of the person who linked it;
- when the store last synced;
- **Notify buyers when shipped**: when it's on, Shopify emails your customer when we add tracking to their order. It's on for every new connection; turn it off if you send your own shipping emails;
- **Open portal**, and links to our privacy policy and terms.

## Reconnect a Shopify store

If your Shopify store's card on the **Stores** page says **Reconnect needed**, we've lost access to the store. Open the app in your Shopify admin: that restores the connection, and the card shows **Connected** again. Then click **Sync now** to fetch orders that came in while we had no access. Tracking that was waiting is sent automatically within about an hour.

## If linking doesn't work

- The portal says "This store is already connected to another account." The store is linked to a different portal account, and a store can belong to one account only. If it's your store, contact your account manager.
- The portal says "This link has expired". Click **Link to portal** in the app again and finish within 30 minutes.
- The app's page still asks you to link the store: reload it after you click **Confirm** in the portal.

To remove the app or unlink the store, see [Disconnect or uninstall](https://docs.rephut.com/shopify/uninstall).

---

Source: https://docs.rephut.com/woocommerce/connect

# Connect WooCommerce

Connect a WooCommerce store from the [Stores page](https://app.rephut.com/stores) in the portal. You can approve the connection in WooCommerce with one click, or create API keys in WordPress and paste them in.

## Before you start

- Your store's address starts with https:// and the store can be reached from the internet.
- No security plugin or firewall blocks WooCommerce's REST API.
- You can sign in to WordPress as an administrator, to approve the connection or create API keys.

## Connect the store

1. In the portal, open **Stores** and click **Connect WooCommerce**.
2. Enter your **Store address**: the address of your shop's home page.
3. Choose **Import orders from**: **New orders only**, **Last 24 hours**, **Last 7 days** or **Last 30 days**. Orders created before that are never imported.
4. Approve the connection in WooCommerce (one-click authorization), or click **Enter API keys manually** and use API keys.

The dialog says "We only import paid orders (status “Processing”)." Orders that are still waiting for payment, for example Pending payment or On hold, come in once WooCommerce moves them to Processing.

![The Connect WooCommerce dialog with Store address, Import orders from and the API key fields](https://docs.rephut.com/images/woo-connect-dialog.png)

### One-click authorization

Click **Authorize in WooCommerce**. Your store's WordPress opens: sign in if asked, check that the request comes from Fulfillbot for your company name, and approve it with Read/Write access. WooCommerce brings you back to the **Stores** page, which waits for the connection to finish and then says "Your store is connected. New paid orders will come in automatically."

Approve the request within 30 minutes, otherwise the connection fails: start again from **Connect WooCommerce**.

If the dialog asks for API keys straight away, one-click authorization isn't available right now: use API keys.

### API keys

1. In WordPress, go to WooCommerce › Settings › Advanced › REST API and add a key.
2. Choose an administrator as the key's user and set the permissions to Read/Write. Generate the key.
3. Copy the consumer key (it starts with ck_) and the consumer secret (it starts with cs_). WooCommerce shows the secret only once.
4. In the portal dialog, paste them into **Consumer key** and **Consumer secret**, and click **Connect store**.

The portal says "Connected. We're importing your paid orders now — refresh in a minute." Read-only keys are refused: the key needs Read/Write permission because we add tracking to your orders and mark them Completed.

## Real-time updates

With real-time updates, your store tells us about new and changed orders as they happen, through webhooks that we add to your store when you connect. If your dialog offers **Authorize in WooCommerce**, you can get real-time updates. Adding the webhooks can fail, though; the next section says what to do then. The store's card shows when the last real-time update arrived.

## Without real-time updates

If the card says **Real-time updates off — use Sync now**, new orders, cancellations and address changes only reach us when you click **Sync now** on the store's card. There is no automatic sync on a timer, so click **Sync now** whenever you want to bring orders in.

**Sync now** also helps when real-time updates are on:

- it fetches anything a real-time update missed;
- it checks the webhooks in your store, and turns them back on or adds them again if WooCommerce turned them off or they were deleted;
- it checks again which tracking plugin your store uses.

One click imports one batch of orders. If there are more, the result says "There are more orders — click Sync now again to continue." You can start a sync of the same store up to 2 times a minute.

## Tracking sent back to WooCommerce

When we ship an order, we add the carrier and tracking number to the WooCommerce order, then mark it Completed:

- with the WooCommerce Shipment Tracking extension, if it's installed;
- otherwise with the Advanced Shipment Tracking plugin, if it's installed;
- otherwise as an order note your customer can see. It starts with "Your order has shipped." and lists the carrier, the tracking number and, when there is one, the tracking link.

An order that is already Completed, Cancelled or Refunded in WooCommerce keeps its status. Your WooCommerce email settings decide whether your customer gets an email when the order is completed or the note is added.

## Next steps

- [Link your store products](https://docs.rephut.com/stores/products)
- [Store orders](https://docs.rephut.com/stores/orders)
- [WooCommerce troubleshooting](https://docs.rephut.com/woocommerce/troubleshooting)

---

Source: https://docs.rephut.com/stores/products

# Link your store products

Linking tells us which of your products to ship for each product in your store. A store order line whose variant is linked matches automatically. A line that isn't linked can still match by SKU; if neither works, the order waits for you as **SKU not mapped**.

## Sync your store's products

On the **Stores** page, click **Sync products** on the store's card. We read your store's products and variants and list them in the portal. Large stores take several rounds; the button keeps going by itself and shows its progress. If it stops before the end, it says "Still syncing — click Sync products again to continue." and the button reads **Continue syncing products**.

Products don't sync on their own. When you add products to your store, click **Sync products** again. After a full sync, variants that are no longer in your store leave **Not linked** and **Not fulfilled by us**; a linked one stays in **Linked**, labelled Removed from store.

Then click **Manage products** to open the store's products.

![A store's products in the portal: the Not linked list with a suggested product, and the Link, Not fulfilled by us and sourcing buttons](https://docs.rephut.com/images/store-products.png)

## The three lists

- **Not linked**: variants that still need a decision. Start here.
- **Linked**: variants linked to one of your products. **Unlink** removes the link; orders that already matched keep their product.
- **Not fulfilled by us**: variants you told us we don't ship. **Restore** puts a variant back in **Not linked**.

You can search all three by product name, option or SKU.

## Link a variant

For each variant in **Not linked**:

- If one of your products in **My products** has the same SKU, the row suggests it. Click **Confirm**. **Confirm all suggestions** links every suggested variant at once.
- Otherwise click **Link** and pick one of your products. You can only pick products that are in **My products**.

Variants of one store product that share a single SKU get no suggestion, so that different options aren't all linked to the same product. Link those one by one.

When you link a variant, orders that were waiting as **SKU not mapped** because of it are updated straight away; the message tells you how many. If a linked product is later removed from **My products**, the row says "Not in My products — orders won't use this link."

## Not fulfilled by us

Use **Not fulfilled by us** for store products we don't ship for you, such as gift wrapping. It only tidies the list: it doesn't change how orders come in. A store order that contains such a product still comes in, and that line shows as **SKU not mapped** unless its SKU matches one of your products. Edit the order to remove the line, or cancel the order if we shouldn't ship any of it.

## Find or source a product you don't have yet

If none of your products match yet:

- **Find by image** opens Search with the store product's image, so you can find a matching product and add it to **My products**. It's there when the variant has an image, and it counts towards your daily image searches. See [Search and the cart](https://docs.rephut.com/sourcing/search#search-by-image).
- **Ask us to source it** opens a sourcing request, filled in with the product's name, link and image. To ask for several at once, tick their rows and click **Ask us to source selected**; one request takes up to 20 variants. See [Sourcing and reorder requests](https://docs.rephut.com/sourcing/requests).

While the request is open, the row shows the request number. Once you accept our quote, the row lists the quoted products that are in **My products**, each with a **Link** button, so you can link the variant straight away.

## How store order lines find a product

For each line of a store order we try, in this order:

1. the variant's link, from this page;
2. the line's SKU: a SKU you added to one of your products in **My products**, our own SKU of a product in **My products**, or your SKU on your agreed price list.

If nothing matches, the line is **SKU not mapped** and the order waits in **Orders** until you fix it. See [Store orders](https://docs.rephut.com/stores/orders#fix-a-store-order).

---

Source: https://docs.rephut.com/stores/orders

# Store orders

Orders from a connected store come in as dropship orders under **Orders**, with your store's order number. This page explains which orders come in, how to fix an order that waits for you, what happens when an order changes in your store, and how tracking gets back to the store.

## Which orders come in

| | Shopify | WooCommerce |
|---|---|---|
| Imported | Orders that are Paid or Partially refunded, and Unfulfilled | Orders with status Processing |
| Treated as cancelled | Cancelled or fully refunded orders | Orders with status Cancelled, Refunded or Failed |
| Lines | Only items that need shipping, at their current quantity | Every line with a quantity |

An order only comes in if it was created on or after the **Import orders from** date you chose when you connected the store. A Shopify order that is partly fulfilled doesn't come in.

These orders don't come in, and the portal doesn't list them:

- orders with more than 200 lines, or with a line whose quantity is above 100,000;
- orders with no lines to ship.

If we should ship one of them, create it in **Orders** yourself (split it into orders within those limits), or contact your account manager.

Orders that an earlier connection of the same store already imported, before you disconnected and connected again, aren't imported a second time: the earlier copy stays in **Orders**.

## Orders to review

If you already have an order with the same order number, created in the portal or imported from a file, we don't import the store order. It waits at the top of the **Stores** page under **Orders to review**: "We didn't import these store orders because you already have an order with the same number." The same happens when another of your store connections already imported the same order.

- **Import anyway** fetches the order from your store again and imports it. If it's no longer waiting to be fulfilled in your store, nothing is imported and the portal says "This order wasn't imported — it's no longer awaiting fulfilment in your store, or it was already handled."
- **Dismiss** keeps it out for this connection.

![Orders to review on the Stores page, with Import anyway and Dismiss](https://docs.rephut.com/images/orders-to-review.png)

## Fix a store order

A store order with a problem waits in **Orders**, with the problem as its status, for example **SKU not mapped**. To fix it:

- link the store variant on the store's products page; orders waiting for that variant update straight away (see [Link your store products](https://docs.rephut.com/stores/products));
- or add the SKU to one of your products in **My products**; orders waiting for that SKU update straight away;
- or open the order and edit it. You can change everything except the store order number, which comes from your store.

Once nothing is left to fix, the order goes ahead like any other order. You can edit or cancel an order only while it waits for you to fix something; after that, contact your account manager to change it.

## When the order changes in your store

We pick up changes to imported orders through real-time updates, and each time you click **Sync now**.

| Change in your store | The order still waits for you, or is **Ready for fulfilment** or **Waiting for stock** | We've started packing the order |
|---|---|---|
| Cancelled | We cancel it | We flag it: "This order was cancelled in your store after we started packing it." |
| New shipping address | We update the address | We flag it: "The shipping address changed in your store after we started packing this order." |
| Different items | We flag it | We flag it |

Once an order no longer waits for you, you can't edit it: contact your account manager. For changed items, the flag says "The items changed in your store. Edit this order to match, or contact your account manager." while the order still waits for you, and "The items changed in your store, but this order can no longer be edited. Contact your account manager to update it." after that.

An order shown as **Awaiting payment** is either **Ready for fulfilment** (we released its stock because the payment wasn't made in time) or already being packed (shipping is waiting for your payment). The first is in the left column, the second in the right one.

A flag shows on the order's **Store** card. Once you've dealt with it, click **Mark as handled**. A flag can only get more serious: a cancellation replaces an address change, for example.

![An imported order with a store change on its Store card and Mark as handled](https://docs.rephut.com/images/order-store-problem.png)

## Orders you ship yourself

Shopify: if you fulfil the whole order in Shopify before we start packing it, we close it in the portal as **Fulfilled by you in your store** and don't ship it. If we've already started, or you fulfil only part of it, we flag it: "This order was marked as fulfilled in your Shopify store. If you don't want us to ship it, contact your account manager." If you undo the fulfilment in Shopify, the order opens again.

WooCommerce doesn't tell us when you ship an order yourself: marking it Completed in WooCommerce changes nothing in the portal. If we shouldn't ship it, cancel it in WooCommerce. We cancel our order too, as long as we haven't started packing it; otherwise contact your account manager.

## Tracking back to your store

When we ship a store order, we send the tracking to the store: in Shopify as a fulfilment, in WooCommerce through a tracking plugin or an order note (see [Connect WooCommerce](https://docs.rephut.com/woocommerce/connect#tracking-sent-back-to-woocommerce)). The order's **Store** card shows how it went:

- "Tracking sent to your store."
- "Sending tracking to your store…" while we're still trying. If the store doesn't answer, we keep trying automatically, up to 6 attempts in all over about 31 hours. While the store needs reconnecting, tracking waits and goes out within about an hour after you reconnect.
- "We couldn't send tracking to your store." Click **Send tracking again**, or add the tracking number in your store yourself.
- "We didn't send tracking: this order has nothing left to fulfil in your store." Shopify only: it was already fulfilled or cancelled in the store.
- "Tracking hasn't been sent to your store." Click **Send tracking again**.
- "This store is disconnected. Add the tracking number in your store yourself."

If we correct the tracking number after shipping, we send the new number to your store automatically. In WooCommerce the old number stays on the order next to the new one.

In Shopify, **Notify buyers when shipped** on the app's page decides whether Shopify emails your customer. See [Install the Shopify app](https://docs.rephut.com/shopify/install#the-app-s-page-in-shopify).

## Cancelling

- Cancelled in your store: see the table above.
- Cancelled in the portal: your store's order isn't touched. Cancel or refund it in your store yourself.

---

Source: https://docs.rephut.com/shopify/uninstall

# Disconnect or uninstall

You can stop a store connection in the portal, for Shopify and WooCommerce stores, or by uninstalling our app in Shopify. Either way, orders that were already imported stay in the portal.

## Disconnect in the portal

On the **Stores** page, click **Disconnect** on the store's card. The card warns "Orders already imported stay. We'll stop sending tracking to this store." Click **Yes, disconnect**. The store disappears from the **Stores** page.

When you disconnect:

- no new orders come in from the store, and changes in the store no longer reach us;
- orders already imported stay, and we go on shipping them, but their tracking isn't sent to the store any more. Once they ship, their **Store** card says "This store is disconnected. Add the tracking number in your store yourself.";
- tracking that was still waiting to be sent isn't sent;
- store orders waiting under **Orders to review** are dismissed;
- your store's products and their links are kept, ready for when you connect the same store again.

WooCommerce: we also remove the webhooks we added to your store. The API key stays in WooCommerce; delete it under WooCommerce › Settings › Advanced › REST API if you no longer need it.

Shopify: the app stays installed, and its page in Shopify shows **Link to portal** again, so you can link the store again later. To remove the app too, uninstall it.

## Uninstall the Shopify app

Uninstall Fulfillbot-Dropship & Branding from the apps list in your Shopify admin. When Shopify tells us, we:

- disconnect the store in the portal, as above, and delete our access to it;
- go on with orders we've already started on (**Waiting for stock**, **Being packed**, **Ready to ship**): they're shipped or cancelled as agreed with you;
- cancel orders we haven't started on (orders still waiting for you, and **Ready for fulfilment**) about 30 days after you uninstall, unless you install the app again before then. We email you the list of cancelled orders, and their recipient details are redacted.

Orders shown as **Awaiting payment** follow the same rule: if we released the stock because the payment wasn't made in time, the order counts as not started (like **Ready for fulfilment**) and gets cancelled; if shipping is waiting for your payment, we've already started packing it and go on with it. Orders we have started on here means anything past **Ready for fulfilment**, including **Waiting for stock**; the store-change rule on [Store orders](https://docs.rephut.com/stores/orders) treats **Waiting for stock** as not started.

Disconnecting in the portal never cancels orders this way: it only applies when the app is uninstalled.

## What happens to your data

For orders from your Shopify store, we replace the recipient's name, company, phone, email, street address, postcode and buyer note with [redacted] 180 days after the order ships or is cancelled. City, region and country stay for accounting and carrier records, as do order numbers, amounts and tracking numbers.

After you uninstall, Shopify asks us to delete the store's data. Unless you've installed the app again by then, we delete the store's name, your synced store products and their links, and redact the recipient details of orders that have ended. Orders still in progress are redacted when they end.

## Install again

Install the app again from the Shopify App Store, then click **Link to portal** on its page, as in [Install the Shopify app](https://docs.rephut.com/shopify/install). This creates a new connection:

- orders the old connection imported aren't imported a second time;
- tracking for those older orders isn't sent to the store, so add it in Shopify yourself;
- if Shopify hasn't asked us to delete the store's data yet, your synced products and links are still there; otherwise click **Sync products** and link them again.

Installing again within 30 days also stops the automatic cancelling of orders we haven't started on.

## Connect a WooCommerce store again

Click **Connect WooCommerce** and connect the same store address again, as in [Connect WooCommerce](https://docs.rephut.com/woocommerce/connect). Orders imported before aren't imported a second time, and your product links are still there. Tracking for orders imported before you disconnected isn't sent to the store.

---

Source: https://docs.rephut.com/woocommerce/troubleshooting

# WooCommerce troubleshooting

What the portal tells you when something goes wrong with a WooCommerce store, and what to do about it.

## Connecting fails

| The portal says | What to do |
|---|---|
| "Enter your store's address, starting with https://." | Enter the full address of your shop's home page. |
| "We couldn't reach your store. Check the address, and make sure the store is online and has WooCommerce installed." | Open the address in a browser. If the store is online, a security plugin or firewall may be blocking WooCommerce's REST API: allow it, then try again. |
| "Your store address redirects to another address. Connect using the address your store redirects to." | Open your store in a browser and use the address it ends up on, for example with or without www. |
| "Your store didn't accept these keys. Check the Consumer key and secret, and make sure the permission is Read/Write." | Copy both keys again, or create a new key with Read/Write permission. |
| "The store granted read-only access. Please connect again and choose Read/Write." | Create a key with Read/Write permission and connect again. |
| "Enter both the Consumer key and the Consumer secret." | Paste both values. |
| "This store is already connected." | It's already on your **Stores** page. |
| "This store is already connected to another account. If it's your store, please contact your account manager." | A store can belong to one account only. |
| "This connection link has expired. Please start again." | Approve the one-click authorization within 30 minutes. Click **Connect WooCommerce** and start again. |
| "One-click connection isn't available right now. Please enter your API keys instead." | Use **Enter API keys manually**. |
| "We can't connect stores right now. Please contact your account manager." | Something is wrong on our side. Try again later, or contact your account manager. |

## The card says Reconnect needed

Your store stopped accepting our access, for example because the API key was deleted or its user lost administrator rights. We also tell you in the portal and by email. The card says "Your store rejected our access keys. Reconnect it so orders keep coming in and tracking gets sent back."

- If the card offers **Reconnect in WooCommerce**, click it and approve access again in WordPress.
- Or create a new Read/Write key, paste it into **Consumer key** and **Consumer secret** on the card, and click **Save keys**.

Tracking that couldn't be sent in the meantime goes out automatically within about an hour after you reconnect. If orders are still missing after a minute, click **Sync now**.

## Orders aren't arriving

1. Check that the card says **Connected**.
2. Check the order's status in WooCommerce: only Processing orders come in.
3. Check the order's date: orders created before your **Import orders from** date never come in. You can't change that date; disconnect and connect again to choose another one.
4. If the card says **Real-time updates off — use Sync now**, orders only come in when you click **Sync now**.
5. Click **Sync now** and read the result. "Sync complete. No new orders." means there was nothing new to import. A result that mentions "your review" means orders are waiting under **Orders to review**. One that mentions "couldn't be processed" means some orders failed on our side; we try them again on the next sync, and if they keep failing, contact your account manager.
6. Check [Store orders](https://docs.rephut.com/stores/orders#which-orders-come-in) for orders we never import.

## Orders arrive only when I click Sync now

The card shows **Real-time updates off — use Sync now** when our webhooks aren't both set up on your store. **Sync now** tries to add them again; if the message stays, click **Sync now** whenever you want new orders, or contact your account manager.

WooCommerce turns a webhook off after it fails several times in a row, and the card can't see that. If orders stopped arriving by themselves although the card doesn't say real-time updates are off, click **Sync now**: it turns our webhooks back on.

## Other messages

| The portal says | What to do |
|---|---|
| "You've synced this store a lot just now. Please wait a minute and try again." | You can start a sync of a store up to 2 times a minute. |
| "This store is already syncing. Please try again in a moment." | Wait for the running sync to finish. |

## What the portal doesn't show

The portal shows what you can act on. Technical details of an error, such as what your server answered, aren't shown. If a problem doesn't go away, contact your account manager and include your store's address.

---

Source: https://docs.rephut.com/stores/faq

# Stores FAQ

### Do I still need to export and import order files?

No. Once your store is connected, paid orders come in by themselves. See [Connect your store](https://docs.rephut.com/stores).

### How quickly do new orders arrive?

With real-time updates, which Shopify stores always have, within moments of being paid. Without them, when you click **Sync now**: there is no sync on a timer. See [Connect WooCommerce](https://docs.rephut.com/woocommerce/connect#without-real-time-updates).

### Can I connect more than one store?

Yes. You can connect several Shopify and WooCommerce stores to one account. Each store can belong to one account only.

### Can I import orders from before I connected?

When you connect, you choose how far back to go: **New orders only**, **Last 24 hours**, **Last 7 days** or **Last 30 days**. You can't change it later.

### Why does an order say SKU not mapped?

One of its lines isn't matched to one of your products. Link the store variant, add the SKU to one of your products, or edit the order. See [Store orders](https://docs.rephut.com/stores/orders#fix-a-store-order).

### An order from my store is missing. Why?

It may be waiting under **Orders to review**, it may not be paid yet, it may be older than your **Import orders from** date, or it may have more than 200 lines. See [Store orders](https://docs.rephut.com/stores/orders#which-orders-come-in).

### I marked a product Not fulfilled by us. Why do its orders still come in?

**Not fulfilled by us** only sorts the product list. Orders with that product still come in, with that line **SKU not mapped** unless its SKU matches one of your products: edit the order to remove the line, or cancel the order. See [Link your store products](https://docs.rephut.com/stores/products#not-fulfilled-by-us).

### Will my customer get a shipping email?

Shopify: yes, if **Notify buyers when shipped** is on. It's on for every new connection unless you turn it off. WooCommerce: we mark the order Completed, and without a tracking plugin we add a note for your customer; your WooCommerce email settings decide which emails go out. See [Store orders](https://docs.rephut.com/stores/orders#tracking-back-to-your-store).

### The tracking number changed after shipping. What now?

We send the new number to your store automatically. If the order's **Store** card says "We couldn't send tracking to your store.", click **Send tracking again**. See [Store orders](https://docs.rephut.com/stores/orders#tracking-back-to-your-store).

### What does Reconnect needed mean?

We lost access to your store. Shopify: open the app in your Shopify admin ([Install the Shopify app](https://docs.rephut.com/shopify/install#reconnect-a-shopify-store)). WooCommerce: see [WooCommerce troubleshooting](https://docs.rephut.com/woocommerce/troubleshooting#the-card-says-reconnect-needed).

### The card says it can't read order details. What do I do?

This only happens with Shopify stores. The card says "We don't have permission to read this store's order details yet, so orders aren't coming in. Please contact your account manager." Please contact your account manager.

### If I disconnect, are my orders deleted?

No. Imported orders stay and we go on shipping them, but tracking isn't sent to the store any more. See [Disconnect or uninstall](https://docs.rephut.com/shopify/uninstall#disconnect-in-the-portal).

### What happens to my orders if I uninstall the Shopify app?

Orders that are **Waiting for stock**, **Being packed** or **Ready to ship** are finished as agreed. Orders still waiting for you, and **Ready for fulfilment** orders, are cancelled about 30 days later, unless you install the app again. See [Disconnect or uninstall](https://docs.rephut.com/shopify/uninstall#uninstall-the-shopify-app).

---

Source: https://docs.rephut.com/faq

# FAQ

### Do you need to approve my account?

No. Your account works as soon as you create it; you may only need to verify your email first. See [Get started](https://docs.rephut.com/start#create-your-account).

### I didn't get the verification email.

Check that you signed up with the right address, then click "Didn't get it? Resend" to get a new link. Use the latest email: the link works for 24 hours. See [Get started](https://docs.rephut.com/start#create-your-account).

### I forgot my password.

Click **Forgot password?** on the sign-in page. If the page doesn't offer it, ask your account manager to reset your password. If you linked Google to your account, you no longer have a password: sign in with Google, or use **Forgot password?** to set one. See [Your account](https://docs.rephut.com/start/account#forgotten-password).

### How do I see what needs me?

Open **To do** in the bell, or **Needs your attention** on **Home**. See [Your account](https://docs.rephut.com/start/account#notifications-and-to-do).

### Why is Available to spend lower than my wallet balance?

Because of the shipping we've set aside for orders we're packing, including orders awaiting payment. See [Your wallet](https://docs.rephut.com/wallet#money-held-for-shipping).

### Why is Available to spend below zero?

The shipping set aside for orders we're packing is more than your balance plus your credit limit, or a **Surcharge** took your balance below your credit limit. Top up enough to bring it back above zero; when shipping is set aside, the **Wallet** page shows the amount to top up. See [Your wallet](https://docs.rephut.com/wallet#money-held-for-shipping).

### How long does a top-up take?

It shows **Pending confirmation** until we've checked your payment, then **Credited**, or **Not accepted** with the reason. Include your reference when you pay, so we can find the payment. See [Top up your wallet](https://docs.rephut.com/wallet/top-up#after-you-submit).

### Can I pay in my own currency?

Yes, if **Currency** offers it for the payment method. The form estimates the value in US dollars, and we confirm the amount when we credit it. See [Top up your wallet](https://docs.rephut.com/wallet/top-up#the-estimate).

### When do you charge for shipping?

When we weigh the packed parcel. Before that, we only set the estimated amount aside. If your wallet can't cover the charge then, we take it just before we ship, once you've topped up. See [When you're charged](https://docs.rephut.com/wallet/charges#dropship-orders).

### What is a surcharge?

Extra shipping we charge after a parcel has shipped, when the carrier billed us for a higher weight than we charged. See [When you're charged](https://docs.rephut.com/wallet/charges#dropship-orders).

### My order says Awaiting payment. What do I do?

Top up your wallet. Once your top-up is credited, we take the charge just before we ship the parcel. A credited top-up first pays any auto purchase orders waiting for payment, so top up enough for both. See [When you're charged](https://docs.rephut.com/wallet/charges#awaiting-payment).

If the order waits too long, we release its stock. It isn't cancelled: it stays under **Needs attention**, and we check stock and pack it again once you've topped up and contacted your account manager. See [When you're charged](https://docs.rephut.com/wallet/charges#unpaid-shipping-charges).

### What does each order status mean?

See [Dropship orders](https://docs.rephut.com/orders#order-statuses).

### Can I change or cancel an order?

Only while it's on hold. After that, contact your account manager. See [Fix an order](https://docs.rephut.com/orders/problems#edit-an-order).

### Why is my order Waiting for stock?

Some of its items aren't in your stock yet. We may buy them for you in a purchase order paid from your wallet, so keep enough in it. We pack the order as soon as everything is in. See [Fix an order](https://docs.rephut.com/orders/problems#waiting-for-stock).

### Can I import orders from a spreadsheet?

Only Shopify's orders export. If you sell on WooCommerce, connect your store instead. See [Place an order](https://docs.rephut.com/orders/place#import-orders-from-a-file).

### Where do I find the tracking number?

On the order's **Fulfilment** card once it has shipped. See [Shipping and tracking](https://docs.rephut.com/orders/shipping#tracking-numbers).

### How do I get a statement?

On **Statements**, for any period of up to 366 days, as a PDF or an Excel file. See [When you're charged](https://docs.rephut.com/wallet/charges#statements).

### How do I buy products through you?

Find them on **Search** and order them from your cart, or send us a sourcing request and accept our quote. To buy more of products you already have agreed prices for, send a reorder request. See [How sourcing works](https://docs.rephut.com/sourcing).

### Is there a smallest quantity I have to buy?

Each product on **Search** shows the smallest total quantity its supplier sells, and you can't add less to your cart. For products we source for you, the quote shows the quantities we priced. See [Search and the cart](https://docs.rephut.com/sourcing/search#the-product-page).

### Why does my cart include shipping before anything has shipped?

That's each supplier's shipping to our warehouse in China. Shipping from our warehouse is charged later: with each dropship order, or with a shipment of your stock. See [Search and the cart](https://docs.rephut.com/sourcing/search#prices).

### Can I withdraw a request?

Yes, while it's **Submitted**. See [Sourcing and reorder requests](https://docs.rephut.com/sourcing/requests#withdraw-a-request).

### Does accepting a quote charge my wallet?

No. Accepting makes the quote's prices your agreed prices. Your account manager then creates a purchase order, which you pay. See [Quotes](https://docs.rephut.com/sourcing/quotes#accept-a-quote).

### How do I pay a purchase order?

Open it and use **Pay from your wallet**, or pay as shown under **How to pay**. Some purchase orders are paid from your wallet automatically. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#pay-a-purchase-order).

### Where can I see photos of my goods?

On the purchase order, under **Warehouse inspection**, once we've checked the delivery in. See [Purchase orders](https://docs.rephut.com/sourcing/purchase-orders#warehouse-inspection).

### What does auto purchase buy?

Only what your orders that are **Waiting for stock** are missing, for the products you've turned it on for, within your daily limit. See [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase).

### Why is auto purchase paused?

A purchase order it created wasn't paid by its due date. Top up, and it resumes once you have enough available. See [Auto purchase](https://docs.rephut.com/sourcing/auto-purchase#overdue-payments-and-pausing).

### What needs my decision?

Items auto purchase held for you, for example because the price went up. See [Product decisions](https://docs.rephut.com/products/decisions).

### Can I hide a product I no longer sell?

Yes, with **Hide** in **My products**. Your SKUs still match it. See [My products](https://docs.rephut.com/products#hide-or-remove-a-product).

### How do I make my store's SKUs match my products?

Add your SKUs to your products in **My products**. See [SKU mapping](https://docs.rephut.com/products/sku-mapping).

### What's the difference between Reserved and Available?

**Reserved** is held for your orders and shipments; **Available** is what's left for new ones. See [Inventory](https://docs.rephut.com/products/inventory#your-stock).

### How do I send stock to my own warehouse or to Amazon FBA?

Create a shipment from **Inventory**. See [Ship your stock](https://docs.rephut.com/shipments).

### How much will shipping cost?

**Shipping rates** in the portal estimates a dropship parcel at your rates. A shipment of your stock shows estimates when you create it, and its freight is worked out from the packed boxes. See [Shipping rates](https://docs.rephut.com/shipments/rates) and [Ship your stock](https://docs.rephut.com/shipments#confirm-the-freight-quote).

Questions about connected stores are answered in [Stores FAQ](https://docs.rephut.com/stores/faq).

---

Source: https://docs.rephut.com/developers

# Fulfillbot API

The Fulfillbot API lets your own systems and AI agents work with your Fulfillbot account. Read your wallet, products, stock, orders, purchase orders, shipments, sourcing requests and quotes; create, fix and cancel orders; map your SKUs; ask for shipments from your stock and confirm their freight quotes; and ask us to source or restock products. Webhooks tell your system when something changes.

The API is another way into the customer portal, not a separate system. Every call follows the same rules as the portal, and what you do through the API shows up in the portal straight away, and the other way round.

## What you need

- **API access for your account.** Fulfillbot turns it on per account: ask your account manager. Until then the portal doesn't show **Settings → API access**.
- **An API key.** Create one in the portal under **Settings → API access**. See [Getting started](https://docs.rephut.com/developers/getting-started).
- **A server or script.** Call the API from your backend. It sends no CORS headers, so browsers can't call it, and a key must never be in a web page or an app.

## Base URL

```text
https://api.rephut.com/v1
```

Every endpoint path in these docs starts with `/v1`. See [Base URL and versioning](https://docs.rephut.com/developers/base-url).

## Before you create orders

Creating orders can hold money in your wallet, and our warehouse charges shipping when it weighs a parcel. Read [Charges and your wallet](https://docs.rephut.com/developers/charges) before you give a key the `orders:write` permission.

## What still needs the portal

Paying purchase orders and shipments, accepting or declining quotes, withdrawing requests, topping up your wallet, uploading images, and managing API keys and webhook endpoints.

## All endpoints

| Endpoint | What it does | Permission |
|---|---|---|
| [`GET /v1/me`](https://docs.rephut.com/developers/reference/account#get-the-customer-and-api-key-for-this-request) | Get the customer and API key for this request | Any valid key |
| [`GET /v1/wallet`](https://docs.rephut.com/developers/reference/wallet#get-the-wallet-balance) | Get the wallet balance | `wallet:read` |
| [`GET /v1/wallet/ledger`](https://docs.rephut.com/developers/reference/wallet#list-wallet-transactions) | List wallet transactions | `wallet:read` |
| [`GET /v1/wallet/top-ups`](https://docs.rephut.com/developers/reference/wallet#list-top-ups) | List top-ups | `wallet:read` |
| [`GET /v1/products`](https://docs.rephut.com/developers/reference/products#list-your-products) | List your products | `catalog:read` |
| [`GET /v1/products/{id}`](https://docs.rephut.com/developers/reference/products#get-one-of-your-products) | Get one of your products | `catalog:read` |
| [`POST /v1/sku-mappings`](https://docs.rephut.com/developers/reference/sku-mappings#map-your-sku-to-one-of-your-products) | Map your SKU to one of your products | `catalog:write` |
| [`GET /v1/inventory`](https://docs.rephut.com/developers/reference/inventory#list-your-stock) | List your stock | `catalog:read` |
| [`GET /v1/orders`](https://docs.rephut.com/developers/reference/orders#list-orders) | List orders | `orders:read` |
| [`GET /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#get-an-order) | Get an order | `orders:read` |
| [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it) | Check a new order without saving it | `orders:read` |
| [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order) | Create an order | `orders:write` |
| [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) | Change an order that needs attention | `orders:write` |
| [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention) | Cancel an order that needs attention | `orders:write` |
| [`GET /v1/purchase-orders`](https://docs.rephut.com/developers/reference/purchase-orders#list-purchase-orders) | List purchase orders | `purchase_orders:read` |
| [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order) | Get a purchase order | `purchase_orders:read` |
| [`GET /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#list-shipments) | List shipments | `shipments:read` |
| [`GET /v1/shipments/{id}`](https://docs.rephut.com/developers/reference/shipments#get-a-shipment) | Get a shipment | `shipments:read` |
| [`POST /v1/shipments/estimate`](https://docs.rephut.com/developers/reference/shipments#estimate-shipping-for-a-shipment-from-your-stock) | Estimate shipping for a shipment from your stock | `shipments:read` |
| [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock) | Request a shipment from your stock | `shipments:write` |
| [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested) | Cancel a shipment you requested | `shipments:write` |
| [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote) | Confirm a shipment's freight quote | `shipments:write` |
| [`GET /v1/requests`](https://docs.rephut.com/developers/reference/requests#list-sourcing-and-reorder-requests) | List sourcing and reorder requests | `requests:read` |
| [`GET /v1/requests/{id}`](https://docs.rephut.com/developers/reference/requests#get-a-sourcing-or-reorder-request) | Get a sourcing or reorder request | `requests:read` |
| [`POST /v1/requests/sourcing`](https://docs.rephut.com/developers/reference/requests#ask-us-to-source-new-products) | Ask us to source new products | `requests:write` |
| [`POST /v1/requests/reorder`](https://docs.rephut.com/developers/reference/requests#ask-us-to-restock-products-at-your-agreed-prices) | Ask us to restock products at your agreed prices | `requests:write` |
| [`GET /v1/quotes`](https://docs.rephut.com/developers/reference/quotes#list-quotes) | List quotes | `quotes:read` |
| [`GET /v1/quotes/{id}`](https://docs.rephut.com/developers/reference/quotes#get-a-quote) | Get a quote | `quotes:read` |

## Docs for AI tools

Every page has a **Markdown** button (the page as plain Markdown, also at its URL plus `.md`), a **Download** button and **Copy for LLM**. [https://docs.rephut.com/llms.txt](https://docs.rephut.com/llms.txt) lists every page, and [https://docs.rephut.com/llms-full.txt](https://docs.rephut.com/llms-full.txt) has all pages in one file. The [OpenAPI document](https://api.rephut.com/v1/openapi.json) describes every endpoint and webhook for tools.

---

Source: https://docs.rephut.com/developers/getting-started

# Getting started

This page takes you from nothing to your first successful request.

## 1. Get API access

Fulfillbot turns API access on per account. Ask your account manager. When it is on, the portal shows **Settings → API access**.

## 2. Create an API key

1. Sign in to the portal and open **Settings → API access**.
2. Under **Create an API key**, enter a name for the key (up to 60 characters), for example the system that will use it.
3. Choose an access level (see the table below). With **Custom** you tick the permissions yourself.
4. Click **Create API key** and copy the key straight away. It is shown only once; we keep only a hash of it.

| Access level | Permissions |
|---|---|
| Read only | `wallet:read`, `catalog:read`, `orders:read`, `purchase_orders:read`, `shipments:read`, `requests:read`, `quotes:read` |
| Read and create orders | `wallet:read`, `catalog:read`, `orders:read`, `purchase_orders:read`, `shipments:read`, `requests:read`, `quotes:read`, `orders:write` |
| Custom | The ones you tick |

When a key can create orders, the portal shows a note about charges first: read [Charges and your wallet](https://docs.rephut.com/developers/charges).

For your security you must have signed in within the last 10 minutes to create a key; otherwise the portal asks you to sign in again. Keys can't be created while your account is on hold. An account can have up to 10 active keys; revoke one you no longer use to add another.

## 3. Store the key safely

Keys start with `pak_`. Treat a key like a password: anyone who has it can use your account within its permissions. Keep it in an environment variable or a secrets manager, never in source code, a web page or a mobile app. The examples in these docs read it from `FULFILLBOT_API_KEY`:

```bash
export FULFILLBOT_API_KEY="pak_..."
```

If a key leaks, revoke it in **Settings → API access**. It stops working at once. Then create a new one.

## 4. Make your first request

[`GET /v1/me`](https://docs.rephut.com/developers/reference/account#get-the-customer-and-api-key-for-this-request) works with any valid key and tells you which account and key a request uses.

```bash example=curl
curl 'https://api.rephut.com/v1/me' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "customer": {
      "id": "cm2x8k1p40000abcd1234wxyz",
      "name": "Northwind Goods"
    },
    "apiKey": {
      "id": "cm3a1b2c30000keyd5678abcd",
      "name": "Order sync",
      "keyPrefix": "pak_7Hq2Lm9X",
      "scopes": [
        "wallet:read",
        "catalog:read",
        "orders:read",
        "purchase_orders:read",
        "shipments:read",
        "requests:read",
        "quotes:read",
        "orders:write"
      ]
    }
  }
}
```

The Node.js examples need Node.js 18 or later (built-in `fetch`, top-level `await`; save them as `.mjs`). The Python examples use the `requests` package (`pip install requests`).

If you get `401 invalid_api_key`, check that the header is exactly `Authorization: Bearer <key>`. If you get `403 api_not_enabled`, API access is off for your account. See [Authentication](https://docs.rephut.com/developers/authentication).

## 5. Next steps

- [Authentication](https://docs.rephut.com/developers/authentication): permissions and why a key can be refused.
- [Errors](https://docs.rephut.com/developers/errors), [Rate limits](https://docs.rephut.com/developers/rate-limits) and [Idempotency](https://docs.rephut.com/developers/idempotency) before you write.
- [Charges and your wallet](https://docs.rephut.com/developers/charges) before you create orders.
- [Webhooks](https://docs.rephut.com/developers/webhooks) so you don't need to poll.
- [From order to delivery](https://docs.rephut.com/developers/guides/order-to-shipment) for a complete walk-through.

---

Source: https://docs.rephut.com/developers/authentication

# Authentication

Every request needs an API key in the `Authorization` header:

```text
Authorization: Bearer pak_...
```

The word `Bearer` is not case-sensitive. Keys are read only from this header, never from query parameters or cookies; the API doesn't use your portal session.

## Permissions

Each key has a list of permissions chosen when you create it. A call without the permission it needs returns `403 insufficient_scope`. [`GET /v1/me`](https://docs.rephut.com/developers/reference/account#get-the-customer-and-api-key-for-this-request) works with any valid key and lists the key's permissions.

| Permission | What it allows | In "Read only" | In "Read and create orders" | Endpoints |
|---|---|---|---|---|
| `wallet:read` | View wallet balance and transactions | Yes | Yes | [`GET /v1/wallet`](https://docs.rephut.com/developers/reference/wallet#get-the-wallet-balance), [`GET /v1/wallet/ledger`](https://docs.rephut.com/developers/reference/wallet#list-wallet-transactions), [`GET /v1/wallet/top-ups`](https://docs.rephut.com/developers/reference/wallet#list-top-ups) |
| `catalog:read` | View products and inventory | Yes | Yes | [`GET /v1/products`](https://docs.rephut.com/developers/reference/products#list-your-products), [`GET /v1/products/{id}`](https://docs.rephut.com/developers/reference/products#get-one-of-your-products), [`GET /v1/inventory`](https://docs.rephut.com/developers/reference/inventory#list-your-stock) |
| `orders:read` | View orders | Yes | Yes | [`GET /v1/orders`](https://docs.rephut.com/developers/reference/orders#list-orders), [`GET /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#get-an-order), [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it) |
| `purchase_orders:read` | View purchase orders | Yes | Yes | [`GET /v1/purchase-orders`](https://docs.rephut.com/developers/reference/purchase-orders#list-purchase-orders), [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order) |
| `shipments:read` | View shipments | Yes | Yes | [`GET /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#list-shipments), [`GET /v1/shipments/{id}`](https://docs.rephut.com/developers/reference/shipments#get-a-shipment), [`POST /v1/shipments/estimate`](https://docs.rephut.com/developers/reference/shipments#estimate-shipping-for-a-shipment-from-your-stock) |
| `requests:read` | View sourcing requests | Yes | Yes | [`GET /v1/requests`](https://docs.rephut.com/developers/reference/requests#list-sourcing-and-reorder-requests), [`GET /v1/requests/{id}`](https://docs.rephut.com/developers/reference/requests#get-a-sourcing-or-reorder-request) |
| `quotes:read` | View quotes | Yes | Yes | [`GET /v1/quotes`](https://docs.rephut.com/developers/reference/quotes#list-quotes), [`GET /v1/quotes/{id}`](https://docs.rephut.com/developers/reference/quotes#get-a-quote) |
| `catalog:write` | Map your SKUs to products | No | No | [`POST /v1/sku-mappings`](https://docs.rephut.com/developers/reference/sku-mappings#map-your-sku-to-one-of-your-products) |
| `orders:write` | Create, change and cancel orders | No | Yes | [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order), [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention), [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention) |
| `shipments:write` | Request, cancel and confirm shipments | No | No | [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock), [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested), [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote) |
| `requests:write` | Submit sourcing and reorder requests | No | No | [`POST /v1/requests/sourcing`](https://docs.rephut.com/developers/reference/requests#ask-us-to-source-new-products), [`POST /v1/requests/reorder`](https://docs.rephut.com/developers/reference/requests#ask-us-to-restock-products-at-your-agreed-prices) |

The access levels you can choose when you create a key:

| Access level | Permissions |
|---|---|
| Read only | `wallet:read`, `catalog:read`, `orders:read`, `purchase_orders:read`, `shipments:read`, `requests:read`, `quotes:read` |
| Read and create orders | `wallet:read`, `catalog:read`, `orders:read`, `purchase_orders:read`, `shipments:read`, `requests:read`, `quotes:read`, `orders:write` |
| Custom | The ones you tick |

Give each integration the smallest set it needs. Permissions can't be changed later: create a new key and revoke the old one.

## Why a key is refused

Keys are checked on every request, so revoking a key or turning API access off takes effect at once.

| Situation | Status | Code |
|---|---|---|
| No `Authorization` header, not a `Bearer` value, or a malformed, unknown or revoked key | 401 | `invalid_api_key` |
| The portal user who created the key was deactivated or no longer belongs to your account | 401 | `invalid_api_key` |
| API access is turned off for your account | 403 | `api_not_enabled` |
| The user who created the key must change a temporary password: sign in to the portal and finish that step | 403 | `account_action_required` |
| The key lacks the permission the endpoint needs | 403 | `insufficient_scope` |
| Your account is on hold: writes are refused, reads keep working | 403 | `account_on_hold` |

Keys don't expire. Changing your portal password doesn't revoke them. When API access is turned off your keys are kept, and they work again when it is turned back on.

## Failed attempts are rate limited

Requests with a malformed, unknown, revoked or no longer valid key (its creator was deactivated or left the account) count as failed attempts for the network (IP address) they come from: 30 an hour and 200 a day. After that, failed attempts get `429 rate_limited` with `Retry-After`. A request without a `Bearer` `Authorization` header doesn't count, and a valid key is never blocked by this, even from the same network. See [Rate limits](https://docs.rephut.com/developers/rate-limits).

## Managing keys

**Settings → API access** lists each key with its name, the start of the key, its permissions, when it was created and when it was last used (updated every few minutes at most). Revoke keys there. We email your account when a key is created. Keys and webhook endpoints can only be managed in the portal, so a program that has a key can't create more keys or add webhook endpoints.

## Keep keys out of browsers

The API sends no CORS headers: calls from a web page fail, and a key in a web page or app is visible to anyone who opens it. Call the API from your server.

---

Source: https://docs.rephut.com/developers/base-url

# Base URL and versioning

## Base URL

```text
https://api.rephut.com/v1
```

All endpoints are under this URL, for example `https://api.rephut.com/v1/me`. Use HTTPS. Any other path on this host returns a JSON `404 not_found`. A path that exists, called with a method it doesn't support, returns `405 method_not_allowed` with an `Allow` header; paths that support `GET` also accept `HEAD`.

## Versioning

The version is the first part of the path, `/v1`. Within `v1` we only add things, so a correct integration keeps working:

- new endpoints;
- new optional request fields;
- new response fields;
- new error codes, event types and status values.

Build your integration so that unknown fields, codes and values don't break it. Rely on `code` and on `status` and `kind` values, never on `error` messages or fields ending in `Label`, which are English text and may change. If a breaking change is ever needed, it will come as a new version (`/v2`), announced in the [Changelog](https://docs.rephut.com/developers/changelog).

## OpenAPI document

[https://api.rephut.com/v1/openapi.json](https://api.rephut.com/v1/openapi.json) describes every endpoint, request and response schema and webhook (OpenAPI 3.1). It is public and needs no key. Use it to generate a client or to load the API into tools such as Postman.

---

Source: https://docs.rephut.com/developers/responses

# Responses and data formats

## Success

```json
{ "success": true, "data": { "id": "cm3o7rd0e0001h2j3k4l5m6n" } }
```

List endpoints add `meta` (see [Pagination](https://docs.rephut.com/developers/pagination)):

```json
{ "success": true, "data": [{ "id": "cm3o7rd0e0001h2j3k4l5m6n" }], "meta": { "total": 120, "page": 1, "limit": 50, "pageCount": 3 } }
```

A call that creates something returns `201` with the new resource. Other successful calls return `200`. Writes return the resource as it is after the change, exactly as the matching `GET` returns it where there is one (for example [`POST /v1/sku-mappings`](https://docs.rephut.com/developers/reference/sku-mappings#map-your-sku-to-one-of-your-products) returns a mapping summary).

## Errors

```json
{ "success": false, "error": "This shipment was updated. Please review it again.", "code": "shipment_changed" }
```

Validation errors add `details`, one entry per problem:

```json
{ "success": false, "error": "Quantities must be at least 1.", "code": "validation_failed", "details": [{ "path": "lines.0.qty", "message": "Quantities must be at least 1." }] }
```

See [Errors](https://docs.rephut.com/developers/errors).

## Headers on every response

| Header | Meaning |
|---|---|
| `X-Request-Id` | A unique id for this request. Quote it when you contact support. |
| `Cache-Control: no-store` | Responses are never cached. |
| `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | Your current rate-limit window, except `403 api_not_enabled`, `403 account_action_required` and unknown paths. See [Rate limits](https://docs.rephut.com/developers/rate-limits). |
| `Retry-After` | On `429` only: seconds to wait. |
| `Idempotency-Replayed: true` | On a replayed response only. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

The public OpenAPI document is the one exception: it may be cached and has no `X-Request-Id`.

## Sending requests

- Send request bodies as JSON with `Content-Type: application/json`. Another content type returns `415 unsupported_media_type`; JSON that doesn't parse returns `400 invalid_json`.
- A body can be at most 1 MB (`413 payload_too_large`) and nested at most 64 levels deep.
- Text can't contain NUL characters (`\u0000`).
- On endpoints that take a body, an empty body returns `422 validation_failed`, except on [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it) and [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention), where an empty body counts as `{}`. Endpoints that take no body, such as [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested), ignore it.
- Fields the endpoint doesn't know are ignored. Text values are trimmed, and control characters are removed from most of them.
- Send each query parameter at most once: a repeated parameter returns `422 validation_failed` on every endpoint. Unknown query parameters are ignored.
- In a query string, encode `+` as `%2B` (for example in a time zone offset); otherwise it arrives as a space.

## Data formats

| Kind | Format |
|---|---|
| Money | Whole numbers of the smallest unit, in fields ending in `Cents`, with the currency in `currency`. Amounts are US dollars (cents), except the supplier reference price of a product, which is Chinese yuan (fen). |
| Times | ISO 8601 in UTC, for example `2026-11-09T02:00:00.000Z`. |
| Dates | Fields that are only a date (payment days, `neededBy`) are `YYYY-MM-DD` in China time (UTC+8). |
| Codes | `status`, `kind` and similar fields are stable uppercase codes such as `SHIPPED`. |
| Labels | Fields ending in `Label` are English text for display. They may change; don't use them in program logic. |
| Ids | Strings of letters, digits, `_` and `-`. Treat them as opaque. An id in a path that isn't in this format returns `404`. |
| Images and files | Not included in responses. |
| Empty values | Text without a value is `""`. Values that don't exist yet are `null`, as each field says. |

## HTTP status codes

| Status | Meaning |
|---|---|
| 200 / 201 | Success / created |
| 400 | Invalid JSON or a bad `Idempotency-Key` |
| 401 | Missing or invalid API key |
| 403 | API access off, an account step needed, a missing permission, or the account on hold |
| 404 | The resource doesn't exist or isn't yours (we don't tell the two apart), or the path doesn't exist |
| 405 | The path exists but not with this method; see `Allow` |
| 409 | The current state doesn't allow it, or the data changed; read it again and decide |
| 413 / 415 | Body over 1 MB / not JSON |
| 422 | The input or a business rule was rejected |
| 429 | Rate limited; wait for `Retry-After` |
| 500 | Unexpected error; quote `X-Request-Id` |

---

Source: https://docs.rephut.com/developers/errors

# Errors

Every error response has the same shape:

```json
{ "success": false, "error": "This order can no longer be changed or cancelled here. Refresh the page to see its latest status.", "code": "order_not_editable" }
```

- `code` is stable and machine-readable. Your program should branch on it.
- `error` is an English message for people. It may change.
- `details` (on `validation_failed` only) lists each problem with the field `path` and a `message`.
- The `X-Request-Id` header identifies the request. Quote it when you contact support.

## How requests are checked

A path that doesn't exist (`404 not_found`) or a wrong method (`405 method_not_allowed`) is answered first. Then the checks run in this order, and the first that fails decides the error:

1. The API key: `401 invalid_api_key`, `403 api_not_enabled`, `403 account_action_required`. Too many failed attempts from one network are answered `429 rate_limited` at this step.
2. The rate limit: `429 rate_limited`. This comes before the permission check, so refused calls still count.
3. The key's permission: `403 insufficient_scope`.
4. For writes, whether your account is on hold: `403 account_on_hold`.
5. The id in the path, if it isn't a valid id: `404 not_found`.
6. The query string and the body: `400 invalid_json`, `413 payload_too_large`, `415 unsupported_media_type`, `422 validation_failed`.
7. The `Idempotency-Key`: `400`, `409 request_in_progress`, `422 idempotency_key_reused`. Errors in the steps above never use up a key.
8. The business rules: a specific code with `404`, `409` or `422`. An id in the path that is valid but doesn't exist or isn't yours returns `404 not_found` on reads, and the endpoint's own code (such as `404 order_not_found`) on writes; each endpoint lists its codes.

## General error codes

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_json` | 400 | The request body is not valid JSON. |
| `idempotency_key_required` | 400 | This request needs an Idempotency-Key header. |
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `method_not_allowed` | 405 | The path exists but does not support this method. The Allow header lists the supported methods. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

## Business rule codes

Business rules return their own codes. Their status follows fixed rules:

- codes ending in `_not_found` are `404`: something in the path doesn't exist or isn't yours;
- codes ending in `_changed` are `409`: the data changed since you read it; read it again and decide again;
- other state conflicts, such as `order_not_editable` or `shipment_not_cancellable`, and uniqueness conflicts, such as `store_order_no_taken` and `library_sku_taken`, are `409`;
- quota and usage limits are `409` as well, because waiting doesn't reliably clear them; don't retry them automatically;
- everything else is `422`. An id inside the request body (a product, a shipping option) that doesn't exist or isn't yours is a `422` rule failure, not a `404`;
- a rule failure we can't describe more precisely is `422 request_rejected`.

The codes each endpoint can return are listed in its reference section. All business codes the API returns today:

| Code | HTTP status | Example message | Returned by |
|---|---|---|---|
| `library_not_in_library` | 422 | This product is not in My products. Please refresh the page. | [`POST /v1/sku-mappings`](https://docs.rephut.com/developers/reference/sku-mappings#map-your-sku-to-one-of-your-products) |
| `library_sku_taken` | 409 | This SKU is already used for another product. | [`POST /v1/sku-mappings`](https://docs.rephut.com/developers/reference/sku-mappings#map-your-sku-to-one-of-your-products) |
| `order_not_editable` | 409 | This order can no longer be changed or cancelled here. Refresh the page to see its latest status. | [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention), [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention) |
| `order_not_found` | 404 | This order could not be found. | [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention), [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention) |
| `order_product_not_allowed` | 422 | Choose products from My products. Other products can't be added to your orders here. | [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it), [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order), [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) |
| `orders_unavailable` | 422 | We can't take orders right now. Please contact your account manager. | [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it), [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order), [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) |
| `preference_channel_unavailable` | 422 | This shipping option is no longer available. Please choose another one. | [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it), [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order), [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention), [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock) |
| `product_not_reorderable` | 422 | One of the products is no longer available to reorder. Please refresh the page and try again. | [`POST /v1/requests/reorder`](https://docs.rephut.com/developers/reference/requests#ask-us-to-restock-products-at-your-agreed-prices) |
| `shipment_changed` | 409 | This shipment was updated. Please review it again. | [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote) |
| `shipment_not_cancellable` | 409 | This shipment can no longer be cancelled here because we've already sent you the freight quote. Please contact your account manager. | [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested) |
| `shipment_not_decidable` | 409 | This shipment can no longer be confirmed or commented on. It may have been updated or already confirmed. Please refresh the page. | [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote) |
| `shipment_not_found` | 404 | This shipment could not be found. | [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested), [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote) |
| `shipments_unavailable` | 422 | We can't take shipments right now. Please contact your account manager. | [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock) |
| `stock_short` | 422 | Some products don't have enough available stock. Refresh the page to see the latest quantities and try again. | [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock) |
| `store_order_no_locked` | 409 | Orders from your store keep the store's order number, so it can't be changed here. | [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) |
| `store_order_no_taken` | 409 | You already have an order with this store order number. | [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order), [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) |
| `unknown_country` | 422 | Choose your country from the list. | [`POST /v1/requests/sourcing`](https://docs.rephut.com/developers/reference/requests#ask-us-to-source-new-products) |

The message column shows the current English text; it may change.

## Handling errors

| Status | What to do |
|---|---|
| 400, 413, 415, 422 | Fix the request. Sending the same request again gives the same error. |
| 401, 403 | Check the key, its permissions and your account in the portal. Don't retry automatically. |
| 404 | Check the id; it may belong to another account. |
| 405 | Use a method from the `Allow` header. |
| 409 | Read the resource again with `GET`, then decide. For `request_in_progress` see [Idempotency](https://docs.rephut.com/developers/idempotency). |
| 429 | Wait the number of seconds in `Retry-After`, then retry. See [Rate limits](https://docs.rephut.com/developers/rate-limits). |
| Network error or timeout on a write | Retry with the same `Idempotency-Key`. The first request may still be running, and a new key could create a duplicate. See [Idempotency](https://docs.rephut.com/developers/idempotency). |
| 500, or `request_in_progress` that doesn't go away | Reads: retry with backoff. Writes: check the current state with `GET`, and use a new `Idempotency-Key` only if the write didn't happen. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

---

Source: https://docs.rephut.com/developers/rate-limits

# Rate limits

Limits apply per account: all your keys share them, so more keys don't mean more requests.

| What | Limit | Counted per |
|---|---|---|
| Reads: every GET, plus [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it) and [`POST /v1/shipments/estimate`](https://docs.rephut.com/developers/reference/shipments#estimate-shipping-for-a-shipment-from-your-stock) | 120 a minute | Account (all your keys together) |
| Writes: every other POST and PATCH | 30 a minute and 2,000 a day | Account (all your keys together) |
| Failed key attempts: malformed, unknown, revoked or no longer valid keys | 30 an hour and 200 a day | Network (IP address); a valid key is never blocked by this |

A minute window starts at the start of each minute, and the day window at midnight UTC.

## Response headers

Responses to requests that pass the key check carry:

| Header | Meaning |
|---|---|
| `RateLimit-Limit` | Requests allowed in the current one-minute window for this kind of request (reads or writes). |
| `RateLimit-Remaining` | Requests left in that window. |
| `RateLimit-Reset` | Seconds until the window resets. It is a number of seconds, not a timestamp. |

The headers show the one-minute window. The exception is a `429` caused by the daily write limit: there `RateLimit-Limit` is 2,000, and `RateLimit-Reset` and `Retry-After` count the seconds to midnight UTC. Otherwise the daily limit isn't shown.

The headers are missing when the key check fails (`401 invalid_api_key`, `403 api_not_enabled`, `403 account_action_required`) and on `404` and `405` answers for unknown paths.

## When you hit a limit

You get `429 rate_limited` with `Retry-After`, the number of seconds to wait. Wait at least that long before the next request of the same kind. Reads and writes are counted separately, so hitting the write limit doesn't stop reads.

A write refused by a rate limit doesn't count towards the daily limit, so a client that retries too early can't use up the day. Writes refused by later checks, such as validation, do count.

## Staying under the limits

- Use [Webhooks](https://docs.rephut.com/developers/webhooks) instead of polling where you can.
- When you poll orders, use `updatedSince` ([Incremental sync](https://docs.rephut.com/developers/incremental-sync)) instead of reading every page each time.
- Spread bulk work out and watch `RateLimit-Remaining`.
- On `429`, wait for `Retry-After`; after repeated `429`s, slow down further.

---

Source: https://docs.rephut.com/developers/idempotency

# Idempotency

Networks fail. When a write times out you can't tell whether it happened. Send an `Idempotency-Key` header and you can safely send the same request again: we run it once and return the saved result to every repeat.

## Which endpoints use it

| Endpoint | Idempotency-Key |
|---|---|
| [`POST /v1/sku-mappings`](https://docs.rephut.com/developers/reference/sku-mappings#map-your-sku-to-one-of-your-products) | Optional |
| [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order) | Required |
| [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) | Optional |
| [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention) | Optional |
| [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock) | Required |
| [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested) | Optional |
| [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote) | Optional |
| [`POST /v1/requests/sourcing`](https://docs.rephut.com/developers/reference/requests#ask-us-to-source-new-products) | Required |
| [`POST /v1/requests/reorder`](https://docs.rephut.com/developers/reference/requests#ask-us-to-restock-products-at-your-agreed-prices) | Required |

Other endpoints ignore the header.

## How it works

- Use a new, unique key for each new request, for example a UUID. A key is 1 to 255 visible ASCII characters (no spaces); anything else returns `400 invalid_idempotency_key`. Where the key is required, a request without it returns `400 idempotency_key_required`.
- Keys belong to your account (all your API keys share them) and are kept for 24 hours. After that, the same key counts as new.
- Once the request has run, we save its response, whatever the status: success or a business error. A repeat with the same key and the same request returns that saved response with the same status and the header `Idempotency-Replayed: true`. It doesn't run again and doesn't change anything.
- "The same request" means the same method, path, query string (in any order) and exactly the same body bytes. The same key with anything different returns `422 idempotency_key_reused`.
- Checks that fail before the request runs (the key, the rate limit, the permission, account on hold, validation) don't use up the idempotency key: fix the request and send it again with the same key.
- While the first request is still running, a repeat returns `409 request_in_progress`.
- Replays still count against the rate limits, including the daily write limit: the limits are checked before the key, so a repeat uses up a request like any other (see [Rate limits](https://docs.rephut.com/developers/rate-limits)). On a network error or timeout, retry with the same key rather than a new one.

## When the result is unknown

We never run a request again on our own when its result is unknown. If a write returned a `5xx`, or `409 request_in_progress` doesn't go away, the write may have happened. For example, an order can be saved even though its response failed.

1. Read the current state with `GET`. For an order, list your orders and look for your `storeOrderNo`.
2. If the write didn't happen, send it again with a **new** key.
3. If it did happen, carry on with what you found.

A network error or timeout is different: the request may still be running, so retry with the **same** key. Only after a saved `5xx`, or a `request_in_progress` that lasts through a few tries, is a new key the way to try again, and only if the write didn't happen. A saved `5xx` keeps coming back for the same key.

## Example: creating an order safely

```js
import { randomUUID } from "node:crypto";

const order = { storeOrderNo: "1042", recipientName: "Alex Morgan", address1: "12 Example Street", city: "Springfield", postalCode: "62701", countryCode: "US", lines: [{ customerSku: "TEE-BLK-M", qty: 2 }] };
// Create the key once per order and store it with the order, so a retry after a crash reuses it.
const idempotencyKey = randomUUID();
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let lastProblem = "no attempt was made";
for (let attempt = 1; attempt <= 5; attempt += 1) {
  let response;
  try {
    response = await fetch("https://api.rephut.com/v1/orders", {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
      body: JSON.stringify(order),
    });
  } catch (error) {
    lastProblem = `network error: ${error.message}`;
    await sleep(1000 * attempt);
    continue; // The first request may still be running. Retry with the same key, never a new one.
  }
  if (response.status === 429) {
    lastProblem = "rate limited";
    await sleep(Number(response.headers.get("retry-after") ?? "1") * 1000);
    continue; // Rate limits are checked before the key is used.
  }
  const result = await response.json();
  if (result.code === "request_in_progress") {
    lastProblem = "the first request is still running";
    await sleep(1000 * attempt);
    continue; // Wait a moment and ask again with the same key.
  }
  if (response.ok) {
    console.log("Order", result.data.number, response.headers.get("idempotency-replayed") ? "(replayed)" : "(created)");
    process.exit(0);
  }
  if (response.status >= 500) {
    throw new Error(`Result unknown (HTTP ${response.status}). Look for the order with GET /v1/orders before using a new key.`);
  }
  throw new Error(`Rejected: ${result.code} ${result.error}`);
}
throw new Error(`Gave up after 5 attempts (${lastProblem}). The order may exist: look for it with GET /v1/orders before using a new key.`);
```

---

Source: https://docs.rephut.com/developers/pagination

# Pagination

List endpoints return one page at a time. Ask for a page with `page`, a whole number from 1 to 10,000 (default 1). Each page has up to 50 items; the page size can't be changed.

```json
{ "success": true, "data": [{ "id": "cm3o7rd0e0001h2j3k4l5m6n" }], "meta": { "total": 120, "page": 2, "limit": 50, "pageCount": 3 } }
```

- `total` is the number of items in the whole list, `pageCount` the number of pages, `limit` the page size and `page` the page you asked for.
- A page after the last one returns an empty `data` list (for example `"data": [], "meta": { "total": 120, "page": 4, "limit": 50, "pageCount": 3 }`, with `meta.page` set to the page you asked for), so reading until `data` is empty works as well as reading up to `pageCount`.
- A `page` that isn't a whole number from 1 to 10,000 returns `422 validation_failed`.
- Each endpoint says how its list is sorted: most are newest first, inventory is sorted by SKU.
- Lists can change while you read them: a new item pushes the others one place on. To mirror your orders, use [Incremental sync](https://docs.rephut.com/developers/incremental-sync).

## Reading every page

```js
async function listAll(path) {
  const items = [];
  for (let page = 1; ; page += 1) {
    const response = await fetch(`https://api.rephut.com/v1${path}?page=${page}`, { headers: { Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}` } });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const { data, meta } = await response.json();
    items.push(...data);
    if (data.length === 0 || page >= meta.pageCount) return items;
  }
}

const products = await listAll("/products");
console.log(products.length, "products");
```

```python
import os

import requests


def list_all(path):
    items = []
    page = 1
    while True:
        response = requests.get(
            f"https://api.rephut.com/v1{path}",
            params={"page": page},
            headers={"Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}"},
            timeout=30,
        )
        response.raise_for_status()
        body = response.json()
        items.extend(body["data"])
        if not body["data"] or page >= body["meta"]["pageCount"]:
            return items
        page += 1


products = list_all("/products")
print(len(products), "products")
```

---

Source: https://docs.rephut.com/developers/incremental-sync

# Incremental sync

To keep a copy of your orders without reading all of them every time, ask [`GET /v1/orders`](https://docs.rephut.com/developers/reference/orders#list-orders) only for the orders that changed.

## How it works

`GET /v1/orders?updatedSince=<time>` returns the orders whose `updatedAt` is at or after that time. The list is still sorted by creation time, newest first, and paged as usual. You can combine it with `status`.

`updatedSince` is an ISO 8601 date-time with a time zone, for example `2026-11-01T00:00:00Z`. Encode `+` in an offset as `%2B`: `2026-11-01T08:00:00%2B08:00`.

## The recipe

1. Note the current time **before** you request page 1. Call it `started`.
2. Read every page with the same `updatedSince`. The first time, leave `updatedSince` out to read everything.
3. Save each order by `id`, replacing the copy you had.
4. Next time, use `started` minus a safety margin of a few minutes as `updatedSince`.

The margin covers clock differences and orders that changed while you were reading. You will see some orders again; that is expected: match them on `id`.

## Things to know

- Any edit through [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention), including a change to the lines only, changes `updatedAt`, so the next `updatedSince` read picks it up.
- Purchase orders, shipments, requests and quotes have no `updatedSince`. Use webhooks and fetch the resource with `GET`, or re-read the first pages of the list (newest first). Re-reading the first pages only finds new purchase orders, shipments and requests, because lists sort by creation time; for changes to older ones use webhooks plus `GET`.
- Webhooks usually tell you about a change within a minute. Polling with `updatedSince` is a good safety net next to them: see [Keep your orders in sync](https://docs.rephut.com/developers/guides/sync-orders).

## Example

```js
import { readFile, writeFile } from "node:fs/promises";

const MARGIN_MS = 5 * 60 * 1000;
const state = JSON.parse(await readFile("sync-state.json", "utf8").catch(() => "{}"));
const started = new Date();
const orders = new Map(Object.entries(state.orders ?? {}));

for (let page = 1; ; page += 1) {
  const query = new URLSearchParams({ page: String(page), ...(state.updatedSince ? { updatedSince: state.updatedSince } : {}) });
  const response = await fetch(`https://api.rephut.com/v1/orders?${query}`, { headers: { Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}` } });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const { data, meta } = await response.json();
  for (const order of data) orders.set(order.id, order);
  if (data.length === 0 || page >= meta.pageCount) break;
}

const updatedSince = new Date(started.getTime() - MARGIN_MS).toISOString();
await writeFile("sync-state.json", JSON.stringify({ updatedSince, orders: Object.fromEntries(orders) }));
console.log(orders.size, "orders saved; next updatedSince:", updatedSince);
```

The list endpoint returns order summaries. Fetch [`GET /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#get-an-order) for the full order, such as the recipient, fulfilment and charges.

---

Source: https://docs.rephut.com/developers/charges

# Charges and your wallet

The API follows the same money rules as the portal. `orders:write` doesn't mean "free": creating orders reserves stock and holds money, and our warehouse charges your wallet when it weighs a parcel. The portal shows this note when you create a key that can create orders:

**Orders created through the API can use your wallet balance**

- Creating an order doesn't charge your wallet. When the order has no problems, we reserve its stock and hold the estimated shipping and handling fee from your available balance.
- When our warehouse weighs the parcel, the shipping and handling fee is charged to your wallet automatically.
- If auto purchase is on and an order is short of stock, we place and pay for a purchase order automatically, within the limits you set.
- Confirming a shipment doesn't charge your wallet. It creates an amount due that you pay separately.

## Step by step

| Action | What happens to your wallet |
|---|---|
| [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it) | Nothing. It shows the hold (`charges.holdCents`) and how much to top up (`charges.topUpCents`). |
| [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order), [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) | No charge. An order without problems reserves its stock; once its stock is fully reserved, it holds the estimated shipping and handling fee from your available balance (`shippingHold` on the order). A `BACKORDERED` order holds nothing yet, and an order with problems holds nothing until it is fixed. |
| [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention) | No charge; the hold, if any, is released. |
| Our warehouse weighs the parcel | The shipping and handling fee is charged to your wallet automatically and the hold is released. If your available balance doesn't cover it, the order waits for payment: `payment` on the order shows the amount, and the webhook `order.awaiting_payment` is sent. Top up in the portal. |
| An order is short of stock and auto purchase is on | We place and pay for a purchase order automatically, within the limits you set in the portal. |
| [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock) | No charge. The stock is reserved. |
| [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote) | No charge. It creates an amount due (`dueCents`), which you pay in the portal. |
| [`POST /v1/requests/sourcing`](https://docs.rephut.com/developers/reference/requests#ask-us-to-source-new-products), [`POST /v1/requests/reorder`](https://docs.rephut.com/developers/reference/requests#ask-us-to-restock-products-at-your-agreed-prices) | No charge. We reply with a quote or a purchase order. |

Your available balance is `availableCents` from [`GET /v1/wallet`](https://docs.rephut.com/developers/reference/wallet#get-the-wallet-balance): `balanceCents + creditLimitCents - heldForShippingCents`. [`GET /v1/wallet/ledger`](https://docs.rephut.com/developers/reference/wallet#list-wallet-transactions) lists every movement.

## Paying

The API can't move money yet. Pay purchase orders and shipments, and top up your wallet, in the portal.

---

Source: https://docs.rephut.com/developers/reference/account

# Account

Use this endpoint to check that a key works and to see which account and permissions it has. It needs no particular permission, so it is a good first call and a good health check.

## Get the customer and API key for this request

`GET /v1/me`

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/me` |
| Permission | Any valid key |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `customer` | object | The account the key belongs to. |
| `customer.id` | string | Your account id. |
| `customer.name` | string | Your company name, as we have it on file. |
| `apiKey` | object | The key that made this request. |
| `apiKey.id` | string | Key id. |
| `apiKey.name` | string | The name you gave the key in the portal. |
| `apiKey.keyPrefix` | string | The first characters of the key, as shown in the portal. They can't be used to authenticate. |
| `apiKey.scopes` | array of strings | The key's permissions, for example `orders:read`. See [Authentication](https://docs.rephut.com/developers/authentication#permissions). |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/me' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "customer": {
      "id": "cm2x8k1p40000abcd1234wxyz",
      "name": "Northwind Goods"
    },
    "apiKey": {
      "id": "cm3a1b2c30000keyd5678abcd",
      "name": "Order sync",
      "keyPrefix": "pak_7Hq2Lm9X",
      "scopes": [
        "wallet:read",
        "catalog:read",
        "orders:read",
        "purchase_orders:read",
        "shipments:read",
        "requests:read",
        "quotes:read",
        "orders:write"
      ]
    }
  }
}
```

---

Source: https://docs.rephut.com/developers/reference/wallet

# Wallet

Your wallet holds the money we charge for shipping, handling, purchase orders and shipments. Amounts are in US cents. The API reads the wallet; top up and pay in the portal. See [Charges and your wallet](https://docs.rephut.com/developers/charges) for when money is held or charged.

Your available balance is `balanceCents + creditLimitCents - heldForShippingCents`. An order without problems holds its estimated shipping and handling fee (`heldForShippingCents`) once its stock is fully reserved; a `BACKORDERED` order holds nothing yet. The hold is released when the order is weighed and charged, cancelled or returned, or when an unpaid hold expires. If the balance is short when the order is weighed, the hold stays.

## Get the wallet balance

`GET /v1/wallet`

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/wallet` |
| Permission | `wallet:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `currency` | string | Currency of every amount in this object. Always `USD`. |
| `balanceCents` | integer | Your wallet balance in US cents. It can be negative when you use your credit limit. |
| `creditLimitCents` | integer | Credit we allow on top of your balance, in US cents. |
| `heldForShippingCents` | integer | Set aside for orders waiting to be packed. |
| `availableCents` | integer | balanceCents + creditLimitCents - heldForShippingCents. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/wallet' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/wallet", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/wallet",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "currency": "USD",
    "balanceCents": 125000,
    "creditLimitCents": 50000,
    "heldForShippingCents": 1840,
    "availableCents": 173160
  }
}
```

## List wallet transactions

`GET /v1/wallet/ledger`

Every top-up, payment, charge and refund that changed the balance. Newest first.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/wallet/ledger` |
| Permission | `wallet:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `id` | string | Transaction id. |
| `createdAt` | string (date-time) | When the transaction was recorded. |
| `kind` | string | What kind of transaction this is. See [Transaction kinds](#transaction-kinds). One of `RECHARGE`, `RECHARGE_VOID`, `GOODS_DEBIT`, `GOODS_REFUND`, `GOODS_REFUND_VOID`, `SHIPPING_DEBIT`, `SURCHARGE`, `ADJUST`, `HANDLING_DEBIT`, `SHIPPING_REFUND`, `HANDLING_REFUND`, `SHIPMENT_DEBIT`, `SHIPMENT_REFUND`, `SHIPMENT_REFUND_VOID`, `SURCHARGE_VOID`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `reference` | string | Order, purchase order or shipment number, or the payment method of a top-up. |
| `currency` | string | Currency of the amounts. Always `USD`. |
| `amountCents` | integer | Change to your balance in US cents: positive adds money, negative takes it away. |
| `balanceAfterCents` | integer | Your balance right after this transaction, in US cents. |
| `note` | string | Only adjustments carry a note. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/wallet/ledger?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/wallet/ledger?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/wallet/ledger?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "id": "cm3l9e1d0002wlt4a8b7c6d5",
      "createdAt": "2026-11-05T09:12:44.000Z",
      "kind": "SHIPPING_DEBIT",
      "kindLabel": "Shipping",
      "reference": "D2611050007",
      "currency": "USD",
      "amountCents": -1240,
      "balanceAfterCents": 125000,
      "note": ""
    },
    {
      "id": "cm3l9e1d0001wlt4a8b7c6d4",
      "createdAt": "2026-11-03T02:30:00.000Z",
      "kind": "RECHARGE",
      "kindLabel": "Top-up",
      "reference": "Bank transfer",
      "currency": "USD",
      "amountCents": 100000,
      "balanceAfterCents": 126240,
      "note": ""
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

## List top-ups

`GET /v1/wallet/top-ups`

Includes pending, rejected and reversed top-ups. Newest first.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/wallet/top-ups` |
| Permission | `wallet:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `id` | string | Top-up id. Webhook `wallet.top_up_approved` carries this id. |
| `status` | string | Top-up status. See [Top-up statuses](#top-up-statuses). One of `PENDING`, `CONFIRMED`, `REJECTED`, `VOIDED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `paidOn` | string (date) | The day the payment was made, as recorded (YYYY-MM-DD, China time). |
| `createdAt` | string (date-time) | When the top-up was recorded. |
| `methodName` | string | The payment method you used. |
| `currency` | string | Currency of the cent amounts. Always `USD`. |
| `paidCents` | integer | Amount paid, in US cents. |
| `feeCents` | integer | Fees taken off, in US cents. |
| `creditedCents` | integer | Amount added to your wallet, in US cents. |
| `originalCurrency` | string | Currency you paid in (ISO 4217). |
| `originalAmountMinor` | integer or null | Amount in the smallest unit of originalCurrency; null for USD. |
| `rejectReason` | string | Why we didn't accept the top-up; empty otherwise. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/wallet/top-ups?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/wallet/top-ups?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/wallet/top-ups?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "id": "cm3t0p0u0001rch9z8y7x6w5",
      "status": "CONFIRMED",
      "statusLabel": "Credited",
      "paidOn": "2026-11-02",
      "createdAt": "2026-11-02T08:15:30.000Z",
      "methodName": "Bank transfer",
      "currency": "USD",
      "paidCents": 100000,
      "feeCents": 0,
      "creditedCents": 100000,
      "originalCurrency": "USD",
      "originalAmountMinor": null,
      "rejectReason": ""
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

## Transaction kinds

| Value | Meaning |
|---|---|
| `RECHARGE` | Top-up: A top-up was credited to your wallet. |
| `RECHARGE_VOID` | Top-up void: An approved top-up was reversed. |
| `GOODS_DEBIT` | Goods payment: Payment for goods, for example a purchase order paid from your wallet. |
| `GOODS_REFUND` | Goods refund: Goods money returned to your wallet, for example when a purchase order is cancelled, goods arrive short, or a wallet payment is voided. |
| `GOODS_REFUND_VOID` | Refund reversal: A goods refund was reversed. |
| `SHIPPING_DEBIT` | Shipping: Shipping charged for an order when it was weighed. |
| `SURCHARGE` | Surcharge: Extra shipping charged after the order shipped, when the carrier bills a higher weight than we charged. |
| `ADJUST` | Adjustment: A manual adjustment by our team; `note` explains it. |
| `HANDLING_DEBIT` | Handling fee: Handling fee charged for an order. |
| `SHIPPING_REFUND` | Shipping refund: Shipping money returned to your wallet. |
| `HANDLING_REFUND` | Handling refund: Handling fee returned to your wallet. |
| `SHIPMENT_DEBIT` | Shipment payment: Payment for a shipment from your stock. |
| `SHIPMENT_REFUND` | Shipment refund: Shipment money returned to your wallet. |
| `SHIPMENT_REFUND_VOID` | Shipment refund reversal: A shipment refund was reversed. |
| `SURCHARGE_VOID` | Surcharge reversal: A surcharge was reversed. |

## Top-up statuses

| Value | Meaning |
|---|---|
| `PENDING` | Waiting for us to check the payment. |
| `CONFIRMED` | Approved and credited to your wallet. |
| `REJECTED` | Not accepted; `rejectReason` says why. |
| `VOIDED` | Approved earlier, then reversed. |

Webhook `wallet.top_up_approved` tells you when a top-up is approved ([Webhook events](https://docs.rephut.com/developers/webhooks/events)).

---

Source: https://docs.rephut.com/developers/reference/products

# Products

These are the products in **My products** in the portal: the products we sourced for you and the ones you added. The list has one item per variant (one SKU), including hidden products and products that can't be ordered right now. Use a product's `id` as `productId` in orders, shipments, reorder requests and SKU mappings.

A product has one of three kinds of price (`price.kind`): your agreed price, a reference price in Chinese yuan from our supplier before you have an agreed price, or none yet. A product can be restocked with a reorder request (`canReorder`) only when it has an agreed price and is available.

The list is sorted by when the product was added, newest first, then by SKU.

## List your products

`GET /v1/products`

Every product in My products, one item per variant, including hidden and unavailable ones. Newest added first, then by SKU.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/products` |
| Permission | `catalog:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `id` | string | Our product id. Use it as `productId` in orders, shipments, reorder requests and SKU mappings. |
| `sku` | string | Our SKU for this product variant. |
| `title` | string | Product name. |
| `variantLabel` | string | Name of this variant, for example its colour and size. |
| `customerSkus` | array of strings | Your SKUs mapped to this product. |
| `quoteCustomerSku` | string or null | Your SKU from the quote, when it is not already mapped. |
| `price` | object | AGREED: your agreed unit price. REFERENCE: the supplier's price before you have an agreed price. NONE: no price yet. |
| `price.kind` | string | Which price this is. See [Price kinds](#price-kinds). One of `AGREED`, `REFERENCE`, `NONE`. |
| `price.currency` | string | Only when `kind` is `AGREED`. Currency of the agreed price. Always `USD`. |
| `price.unitPriceCents` | integer | Only when `kind` is `AGREED`. Your agreed unit price in US cents. |
| `price.currency` | string | Only when `kind` is `REFERENCE`. Currency of the reference price. Always `CNY`. |
| `price.unitPriceCents` | integer | Only when `kind` is `REFERENCE`. Current supplier price in fen (1/100 CNY). |
| `price.approxUsdCents` | integer or null | Only when `kind` is `REFERENCE`. Rough USD equivalent; null when no exchange rate is set. |
| `price.checkedAt` | string (date-time) | Only when `kind` is `REFERENCE`. When we last checked the supplier's price. |
| `availableQty` | integer | Units of this product in our warehouse that are free to use (not set aside for orders or shipments). |
| `available` | boolean | `false` when the product can't be ordered right now; `inactiveReason` says why. |
| `inactiveReason` | string | Why the product is unavailable; empty when it is available or we gave no reason. |
| `hidden` | boolean | `true` when you hid the product in My products. Hidden products are still listed here. |
| `canReorder` | boolean | `true` when the product has an agreed price and is available, so you can restock it with [`POST /v1/requests/reorder`](https://docs.rephut.com/developers/reference/requests#ask-us-to-restock-products-at-your-agreed-prices). |
| `weightKnown` | boolean | `false` while we don't know the product's weight. Order shipping estimates then use an assumed weight; [`POST /v1/shipments/estimate`](https://docs.rephut.com/developers/reference/shipments#estimate-shipping-for-a-shipment-from-your-stock) counts the product as 0 g. |
| `addedAt` | string (date-time) | When the product was added to My products; for a product with an agreed price that was never added, when the agreed price took effect. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/products?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/products?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/products?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "id": "cm3p4r0d0002xyz7k2m9q8w2",
      "sku": "FB-10388-WHT",
      "title": "Ceramic mug 350 ml",
      "variantLabel": "White",
      "customerSkus": [],
      "quoteCustomerSku": "MUG-WHT",
      "price": {
        "kind": "REFERENCE",
        "currency": "CNY",
        "unitPriceCents": 1250,
        "approxUsdCents": 176,
        "checkedAt": "2026-11-01T06:00:00.000Z"
      },
      "availableQty": 0,
      "available": true,
      "inactiveReason": "",
      "hidden": false,
      "canReorder": false,
      "weightKnown": false,
      "addedAt": "2026-11-01T06:00:00.000Z"
    },
    {
      "id": "cm3p4r0d0001xyz7k2m9q8w1",
      "sku": "FB-10231-BLK-M",
      "title": "Cotton crew neck T-shirt",
      "variantLabel": "Black / M",
      "customerSkus": [
        "TEE-BLK-M"
      ],
      "quoteCustomerSku": null,
      "price": {
        "kind": "AGREED",
        "currency": "USD",
        "unitPriceCents": 385
      },
      "availableQty": 140,
      "available": true,
      "inactiveReason": "",
      "hidden": false,
      "canReorder": true,
      "weightKnown": true,
      "addedAt": "2026-10-20T03:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

## Get one of your products

`GET /v1/products/{id}`

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/products/{id}` |
| Permission | `catalog:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Product id, from [`GET /v1/products`](https://docs.rephut.com/developers/reference/products#list-your-products). An id that doesn't exist, isn't yours or isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Our product id. Use it as `productId` in orders, shipments, reorder requests and SKU mappings. |
| `sku` | string | Our SKU for this product variant. |
| `title` | string | Product name. |
| `variantLabel` | string | Name of this variant, for example its colour and size. |
| `customerSkus` | array of strings | Your SKUs mapped to this product. |
| `quoteCustomerSku` | string or null | Your SKU from the quote, when it is not already mapped. |
| `price` | object | AGREED: your agreed unit price. REFERENCE: the supplier's price before you have an agreed price. NONE: no price yet. |
| `price.kind` | string | Which price this is. See [Price kinds](#price-kinds). One of `AGREED`, `REFERENCE`, `NONE`. |
| `price.currency` | string | Only when `kind` is `AGREED`. Currency of the agreed price. Always `USD`. |
| `price.unitPriceCents` | integer | Only when `kind` is `AGREED`. Your agreed unit price in US cents. |
| `price.currency` | string | Only when `kind` is `REFERENCE`. Currency of the reference price. Always `CNY`. |
| `price.unitPriceCents` | integer | Only when `kind` is `REFERENCE`. Current supplier price in fen (1/100 CNY). |
| `price.approxUsdCents` | integer or null | Only when `kind` is `REFERENCE`. Rough USD equivalent; null when no exchange rate is set. |
| `price.checkedAt` | string (date-time) | Only when `kind` is `REFERENCE`. When we last checked the supplier's price. |
| `availableQty` | integer | Units of this product in our warehouse that are free to use (not set aside for orders or shipments). |
| `available` | boolean | `false` when the product can't be ordered right now; `inactiveReason` says why. |
| `inactiveReason` | string | Why the product is unavailable; empty when it is available or we gave no reason. |
| `hidden` | boolean | `true` when you hid the product in My products. Hidden products are still listed here. |
| `canReorder` | boolean | `true` when the product has an agreed price and is available, so you can restock it with [`POST /v1/requests/reorder`](https://docs.rephut.com/developers/reference/requests#ask-us-to-restock-products-at-your-agreed-prices). |
| `weightKnown` | boolean | `false` while we don't know the product's weight. Order shipping estimates then use an assumed weight; [`POST /v1/shipments/estimate`](https://docs.rephut.com/developers/reference/shipments#estimate-shipping-for-a-shipment-from-your-stock) counts the product as 0 g. |
| `addedAt` | string (date-time) | When the product was added to My products; for a product with an agreed price that was never added, when the agreed price took effect. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/products/cm3p4r0d0001xyz7k2m9q8w1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/products/cm3p4r0d0001xyz7k2m9q8w1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/products/cm3p4r0d0001xyz7k2m9q8w1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3p4r0d0001xyz7k2m9q8w1",
    "sku": "FB-10231-BLK-M",
    "title": "Cotton crew neck T-shirt",
    "variantLabel": "Black / M",
    "customerSkus": [
      "TEE-BLK-M"
    ],
    "quoteCustomerSku": null,
    "price": {
      "kind": "AGREED",
      "currency": "USD",
      "unitPriceCents": 385
    },
    "availableQty": 140,
    "available": true,
    "inactiveReason": "",
    "hidden": false,
    "canReorder": true,
    "weightKnown": true,
    "addedAt": "2026-10-20T03:00:00.000Z"
  }
}
```

## Price kinds

| Value | Meaning |
|---|---|
| `AGREED` | Your agreed unit price in US cents. |
| `REFERENCE` | The supplier's current price in fen (CNY), before you have an agreed price, with a rough USD equivalent. |
| `NONE` | No price yet. |

---

Source: https://docs.rephut.com/developers/reference/inventory

# Inventory

Your stock in our warehouse, per product: what is on hand, what is set aside for orders and shipments, what is free to use, and what is on the way from purchase orders. Dropship orders use it automatically; ship it in bulk with [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock).

The list contains every product that has stock on hand, stock set aside, or stock on the way. It is sorted by SKU.

## List your stock

`GET /v1/inventory`

Products with stock in our warehouse, stock set aside for orders, or stock on the way. Sorted by SKU.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/inventory` |
| Permission | `catalog:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `productId` | string | Our product id. Use it in [`POST /v1/shipments/estimate`](https://docs.rephut.com/developers/reference/shipments#estimate-shipping-for-a-shipment-from-your-stock) and [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock). |
| `sku` | string | Our SKU. |
| `name` | string | Product name in English. |
| `attributes` | string | Variant details in English, for example colour and size. |
| `customerSku` | string | Your SKU for this product when it is mapped; empty otherwise. |
| `onHandQty` | integer | Units in our warehouse. |
| `reservedQty` | integer | Units set aside for orders and shipments. |
| `availableQty` | integer | Units free to use: `onHandQty` minus `reservedQty`. |
| `incomingQty` | integer | Bought but not yet in our warehouse. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/inventory?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/inventory?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/inventory?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "productId": "cm3p4r0d0001xyz7k2m9q8w1",
      "sku": "FB-10231-BLK-M",
      "name": "Cotton crew neck T-shirt",
      "attributes": "Black / M",
      "customerSku": "TEE-BLK-M",
      "onHandQty": 160,
      "reservedQty": 20,
      "availableQty": 140,
      "incomingQty": 200
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

---

Source: https://docs.rephut.com/developers/reference/sku-mappings

# SKU mappings

Orders from your store or from files use your own SKUs. A mapping tells us which of your products a SKU is, so order lines match by themselves. An order line whose SKU isn't mapped, and that has no `productId`, makes the order need attention (problem `UNBOUND_LINE`).

- A SKU maps to one product. To move it to another product, send `move: true`; without it you get `409 library_sku_taken`.
- The product must be in My products, otherwise you get `422 library_not_in_library`.
- Orders waiting for this SKU are matched again straight away, and the response says how many. They go through the same checks as saving an order, so they can move on: stock reserved, shipping fee held, auto purchase may run. If `moreOrders` is `true`, save the remaining orders again with [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) to match them.
- A product's mapped SKUs are in `customerSkus` from [`GET /v1/products`](https://docs.rephut.com/developers/reference/products#list-your-products). Mappings can't be removed through the API; remove them in the portal.

## Map your SKU to one of your products

`POST /v1/sku-mappings`

Adds your SKU to a product in My products, like adding a SKU on the portal's My products page. Orders that need attention because of this SKU are matched again right away. A product that isn't in My products returns 422 library_not_in_library.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/sku-mappings` |
| Permission | `catalog:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Optional, recommended |
| Success | 201 Created |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

A JSON object. Fields not listed here are ignored.

| Field | Type | Required | Description |
|---|---|---|---|
| `customerSku` | string | Yes | Your SKU, as it appears on your orders. 1 to 100 characters. |
| `productId` | string | Yes | Our product id from GET /v1/products (a product in My products). 1 to 64 characters. |
| `move` | boolean | No | Your SKU is already mapped to another product: send true to move it to this product. Otherwise you get 409 library_sku_taken. Default: `false`. |

### Response

`201` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `customerSku` | string | Your SKU, as saved. |
| `productId` | string | The product the SKU now maps to. |
| `rematchedOrders` | integer | Orders waiting on this SKU that now use the product. |
| `ordersStillNeedingAttention` | integer | Of those orders, how many still need other fixes. |
| `moreOrders` | boolean | More waiting orders use this SKU than we updated now; save them again with PATCH /v1/orders/{id} to match them. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `library_sku_taken` | 409 | This SKU is already used for another product. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `library_not_in_library` | 422 | This product is not in My products. Please refresh the page. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/sku-mappings' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: 0b7e2d8c-5a14-4f3b-9c61-2d8e7f1a4b90' \
  -d '{
  "customerSku": "MUG-WHT",
  "productId": "cm3p4r0d0002xyz7k2m9q8w2"
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/sku-mappings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "0b7e2d8c-5a14-4f3b-9c61-2d8e7f1a4b90",
  },
  body: JSON.stringify({
    "customerSku": "MUG-WHT",
    "productId": "cm3p4r0d0002xyz7k2m9q8w2"
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/sku-mappings",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "0b7e2d8c-5a14-4f3b-9c61-2d8e7f1a4b90",
    },
    json={
        "customerSku": "MUG-WHT",
        "productId": "cm3p4r0d0002xyz7k2m9q8w2",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=201
{
  "success": true,
  "data": {
    "customerSku": "MUG-WHT",
    "productId": "cm3p4r0d0002xyz7k2m9q8w2",
    "rematchedOrders": 2,
    "ordersStillNeedingAttention": 0,
    "moreOrders": false
  }
}
```

---

Source: https://docs.rephut.com/developers/reference/orders

# Orders

Dropship orders: we pick, pack and ship each order from your stock in our warehouse to your buyer. Orders come from connected stores, file imports, the portal and the API; all of them are listed here.

## How an order moves

- An order that is missing something is saved with status `NEEDS_ATTENTION`, and `problems` says what to fix. Otherwise it goes on to fulfilment.
- Stock is reserved automatically when you save the order: it becomes `RESERVED`, or `BACKORDERED` when stock is short. Our warehouse then weighs (`WEIGHED`) and ships (`SHIPPED`) it. `CANCELLED` ends it.
- Only orders with status `NEEDS_ATTENTION` can be changed or cancelled through the API (`409 order_not_editable` otherwise). For other orders, contact your account manager.
- Webhook `order.status_changed` reports every status change, and `order.awaiting_payment` tells you when the shipping fee is waiting for funds ([Webhook events](https://docs.rephut.com/developers/webhooks/events)).

## Order statuses

| Value | Meaning |
|---|---|
| `NEEDS_ATTENTION` | Something must be fixed before we can fulfil the order; `problems` says what. Fix it with PATCH or cancel it. `statusLabel` names the first problem. |
| `READY` | Ready for fulfilment: the order has no problems and waits for our warehouse. This is usually brief. An order also returns here if an unpaid shipping hold expires and its stock is released. |
| `BACKORDERED` | Waiting for stock: some products are short; `backorder` lists them and the purchase orders bringing them. |
| `RESERVED` | Being packed: the stock is set aside and our warehouse is packing the order. If your available balance didn't cover the shipping and handling fee when the parcel was weighed, the order stays here and `payment` shows the amount due. |
| `WEIGHED` | Ready to ship: the parcel is weighed and the shipping and handling fee is charged to your wallet. |
| `SHIPPED` | Shipped. `fulfilment` has the tracking number and the amounts charged. An order your store marked as fulfilled has `shippedInStore: true`, is not charged and may have no `fulfilment`; the store can reopen it. |
| `CANCELLED` | Cancelled. `cancelledAt` says when. |

## Order problems

`problems` lists why an order needs attention. Rely on `code`; `message` is English text that may change.

| Value | Meaning |
|---|---|
| `NO_LINES` | The order has no items. |
| `UNBOUND_LINE` | A line's SKU isn't mapped to one of your products. Map it with POST /v1/sku-mappings or set the line's `productId`. |
| `MISSING_RECIPIENT` | The recipient's name or address is incomplete. |
| `UNKNOWN_COUNTRY` | The country is missing or isn't one we ship to. |
| `NO_CHANNEL` | No shipping option is chosen and your shipping preference doesn't pick one for this country. |
| `CHANNEL_UNAVAILABLE` | The chosen shipping option can't take this order, for example because of the country or the weight. |

## Creating orders

1. Map your SKUs ([SKU mappings](https://docs.rephut.com/developers/reference/sku-mappings)), or put our `productId` on each line.
2. Check the order with [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it): problems, shipping options and prices, the wallet hold and stock shortages. Nothing is saved.
3. Create it with [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order) and an `Idempotency-Key`.
4. If it comes back `NEEDS_ATTENTION`, fix it with [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) (send the whole order again) or cancel it with [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention).

Shipping: leave `channelId` empty to use your shipping preference for the country (set in the portal), or send a `channelId` from `shippingOptions` in the preview. `storeOrderNo` must be unique among your orders (`409 store_order_no_taken`); leave it empty to use our order number. For an order from a connected store, `storeOrderNo` can't be changed: a different value is rejected with `store_order_no_locked`.

Read [Charges and your wallet](https://docs.rephut.com/developers/charges) first: an order without problems holds its estimated shipping and handling fee in your wallet once its stock is fully reserved (a `BACKORDERED` order holds nothing yet). The full walk-through is in [From order to delivery](https://docs.rephut.com/developers/guides/order-to-shipment).

## List orders

`GET /v1/orders`

Newest first (by creation time). Filter by one `status`, or by `updatedSince` to get orders changed at or after that time. To sync without webhooks, note the time just before you request page 1, read every page with the same `updatedSince`, then use that time minus a safety margin (for example 5 minutes) as `updatedSince` next time. Expect to see some orders again and match them on `id`. Any edit through `PATCH /v1/orders/{id}` changes `updatedAt`.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/orders` |
| Permission | `orders:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |
| `status` | string | No | One order status, uppercase, for example SHIPPED. One of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`. |
| `updatedSince` | string (date-time) | No | ISO 8601 date-time with a time zone, for example 2026-11-01T00:00:00Z. Send a + in an offset as %2B (2026-11-01T08:00:00%2B08:00), or it arrives as a space and is rejected. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `id` | string | Order id. |
| `number` | string | Our order number. |
| `storeOrderNo` | string | Your store's order number; empty when you didn't give one. |
| `status` | string | Order status. See [Order statuses](#order-statuses). One of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. For `NEEDS_ATTENTION` it names the first problem, for example "SKU not mapped". |
| `recipientName` | string | Recipient name. |
| `country` | string | Destination country in English. If we don't recognise it, the text the order has, or the code itself when the code is unknown; "—" when there is neither. |
| `countryCode` | string or null | Two-letter destination country code; null when we don't recognise the country. |
| `itemCount` | integer | Total quantity of all lines. |
| `lines` | array of objects | The items in the order. |
| `lines[].productId` | string or null | Our product id; null while the line is not matched to a product. |
| `lines[].productSku` | string or null | Our SKU of the matched product; null while the line isn't matched. |
| `lines[].productName` | string or null | Name of the matched product; null while the line isn't matched. |
| `lines[].customerSku` | string | Your SKU on this line. |
| `lines[].title` | string | Item name from your store or file. |
| `lines[].qty` | integer | Quantity. |
| `createdAt` | string (date-time) | When the order was created. |
| `updatedAt` | string (date-time) | When the order last changed. Any edit through [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) changes it. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/orders?updatedSince=2026-11-01T00%3A00%3A00Z' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/orders?updatedSince=2026-11-01T00%3A00%3A00Z", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/orders?updatedSince=2026-11-01T00%3A00%3A00Z",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "id": "cm3o7rd0e0001h2j3k4l5m6n",
      "number": "D2611090012",
      "storeOrderNo": "1042",
      "status": "READY",
      "statusLabel": "Ready for fulfilment",
      "recipientName": "Alex Morgan",
      "country": "United States",
      "countryCode": "US",
      "itemCount": 2,
      "lines": [
        {
          "productId": "cm3p4r0d0001xyz7k2m9q8w1",
          "productSku": "FB-10231-BLK-M",
          "productName": "Cotton crew neck T-shirt",
          "customerSku": "TEE-BLK-M",
          "title": "Crew neck T-shirt, black, M",
          "qty": 2
        }
      ],
      "createdAt": "2026-11-09T02:00:00.000Z",
      "updatedAt": "2026-11-09T02:00:00.000Z"
    },
    {
      "id": "cm3o7rd0e0000h2j3k4l5m6m",
      "number": "D2611050007",
      "storeOrderNo": "1039",
      "status": "SHIPPED",
      "statusLabel": "Shipped",
      "recipientName": "Alex Morgan",
      "country": "United Kingdom",
      "countryCode": "GB",
      "itemCount": 1,
      "lines": [
        {
          "productId": "cm3p4r0d0001xyz7k2m9q8w1",
          "productSku": "FB-10231-BLK-M",
          "productName": "Cotton crew neck T-shirt",
          "customerSku": "TEE-BLK-M",
          "title": "Crew neck T-shirt, black, M",
          "qty": 1
        }
      ],
      "createdAt": "2026-11-05T01:20:00.000Z",
      "updatedAt": "2026-11-07T10:05:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

## Get an order

`GET /v1/orders/{id}`

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/orders/{id}` |
| Permission | `orders:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Order id, from [`GET /v1/orders`](https://docs.rephut.com/developers/reference/orders#list-orders) or the response of [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order). An id that doesn't exist, isn't yours or isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Order id. |
| `number` | string | Our order number. |
| `storeOrderNo` | string | Your store's order number; empty when you didn't give one. |
| `status` | string | Order status. See [Order statuses](#order-statuses). One of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. For `NEEDS_ATTENTION` it names the first problem, for example "SKU not mapped". |
| `sourceLabel` | string | Where the order came from: `Store` (a connected store), `Imported` (a file import) or `Manual` (the portal form or the API). English text; it may change. |
| `createdAt` | string (date-time) | When the order was created. |
| `updatedAt` | string (date-time) | When the order last changed. Any edit through [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) changes it. |
| `cancelledAt` | string (date-time) or null | When the order was cancelled; null otherwise. |
| `recipient` | object | Who we ship to. |
| `recipient.name` | string | Recipient name. |
| `recipient.company` | string | Company; empty when none. |
| `recipient.phone` | string | Recipient phone number. |
| `recipient.email` | string | Recipient email address. |
| `recipient.address1` | string | Address line 1. |
| `recipient.address2` | string | Address line 2. |
| `recipient.city` | string | City. |
| `recipient.province` | string | State or province. |
| `recipient.postalCode` | string | Postal code. |
| `recipient.country` | string | Country in English. If we don't recognise it, the text the order has, or the code itself when the code is unknown; "—" when there is neither. |
| `recipient.countryCode` | string or null | Two-letter country code; null when we don't recognise the country. |
| `buyerNote` | string | Note from your buyer. |
| `lines` | array of objects | The items in the order. |
| `lines[].productId` | string or null | Our product id; null while the line is not matched to a product. |
| `lines[].productSku` | string or null | Our SKU of the matched product; null while the line isn't matched. |
| `lines[].productName` | string or null | Name of the matched product; null while the line isn't matched. |
| `lines[].customerSku` | string | Your SKU on this line. |
| `lines[].title` | string | Item name from your store or file. |
| `lines[].qty` | integer | Quantity. |
| `shippingChannelLabel` | string | The shipping option the order uses, in English; `Assigned by our team` when we chose it, `—` when none is set yet. |
| `shippedInStore` | boolean | `true` when you fulfilled the order yourself in your store, so we don't ship it. |
| `currency` | string | Currency of every amount in this order. Always `USD`. |
| `estimatedShippingCents` | integer or null | Estimated shipping in US cents; null when it can't be estimated yet, and when `shippedInStore` is `true`. |
| `weightEstimated` | boolean | `true` when a product's weight is unknown and the estimate uses an assumed weight. Only before the parcel is weighed; `false` afterwards. |
| `problems` | array of objects | Why the order needs attention; empty otherwise. Rely on `code`; `message` is English text that may change. |
| `problems[].code` | string | Problem code. See [Order problems](#order-problems). One of `NO_LINES`, `UNBOUND_LINE`, `MISSING_RECIPIENT`, `UNKNOWN_COUNTRY`, `NO_CHANNEL`, `CHANNEL_UNAVAILABLE`. |
| `problems[].message` | string | English text for display. It may change; rely on the code next to it. |
| `fulfilment` | object or null | What our warehouse did with the parcel. Present when the status is `RESERVED`, `WEIGHED` or `SHIPPED`; null otherwise. |
| `fulfilment.trackingNo` | string | Tracking number; empty until the parcel ships. |
| `fulfilment.trackingUrl` | string or null | Link to track the parcel; null when we have none. |
| `fulfilment.shippedAt` | string (date-time) or null | When the parcel shipped; null until then. |
| `fulfilment.actualWeightG` | integer or null | Weighed parcel weight in grams; null until weighed. |
| `fulfilment.freightCents` | integer or null | Shipping charged, in US cents; null until charged. |
| `fulfilment.handlingFeeCents` | integer or null | Handling fee charged, in US cents; null until charged. |
| `fulfilment.surchargeCents` | integer or null | Extra shipping charged later (for example a carrier adjustment), in US cents; null when none. |
| `fulfilment.totalChargedCents` | integer or null | Everything charged for this order, in US cents; null until charged. |
| `payment` | object or null | Shipping charge waiting for wallet funds; null when nothing is due. |
| `payment.freightCents` | integer | Shipping fee waiting to be paid, in US cents. |
| `payment.handlingFeeCents` | integer | Handling fee waiting to be paid, in US cents. |
| `payment.dueCents` | integer | Total waiting to be paid, in US cents. |
| `payment.availableCents` | integer | Your available balance plus the amount already held for this order, in US cents. |
| `payment.topUpCents` | integer | At least this much to top up. |
| `shippingHold` | object or null | The estimated shipping and handling fee held from your available balance while the order waits to ship; null when nothing is held. See [Charges and your wallet](https://docs.rephut.com/developers/charges). |
| `shippingHold.heldCents` | integer | Amount held, in US cents. |
| `shippingHold.topUpCents` | integer | Top up at least this much when your balance doesn't cover the hold; 0 when it does. |
| `backorder` | object or null | What the order is waiting for when some products are short; null otherwise. |
| `backorder.lines` | array of objects | Products short for this order. |
| `backorder.lines[].productSku` | string | Our SKU. |
| `backorder.lines[].productName` | string | Product name. |
| `backorder.lines[].orderedQty` | integer | Quantity ordered. |
| `backorder.lines[].waitingQty` | integer | Quantity still waiting for stock. |
| `backorder.purchaseOrders` | array of objects | Purchase orders that bring the missing stock. |
| `backorder.purchaseOrders[].id` | string | Purchase order id. Fetch it with [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order). |
| `backorder.purchaseOrders[].number` | string | Purchase order number. |
| `backorder.purchaseOrders[].statusLabel` | string | English text for display. It may change; rely on the code next to it. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3o7rd0e0001h2j3k4l5m6n",
    "number": "D2611090012",
    "storeOrderNo": "1042",
    "status": "READY",
    "statusLabel": "Ready for fulfilment",
    "sourceLabel": "Manual",
    "createdAt": "2026-11-09T02:00:00.000Z",
    "updatedAt": "2026-11-09T02:00:00.000Z",
    "cancelledAt": null,
    "recipient": {
      "name": "Alex Morgan",
      "company": "",
      "phone": "+1 555 0100",
      "email": "alex@example.com",
      "address1": "12 Example Street",
      "address2": "Apt 4",
      "city": "Springfield",
      "province": "IL",
      "postalCode": "62701",
      "country": "United States",
      "countryCode": "US"
    },
    "buyerNote": "Please leave at the door.",
    "lines": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "productSku": "FB-10231-BLK-M",
        "productName": "Cotton crew neck T-shirt",
        "customerSku": "TEE-BLK-M",
        "title": "Crew neck T-shirt, black, M",
        "qty": 2
      }
    ],
    "shippingChannelLabel": "US Standard",
    "shippedInStore": false,
    "currency": "USD",
    "estimatedShippingCents": 640,
    "weightEstimated": false,
    "problems": [],
    "fulfilment": null,
    "payment": null,
    "shippingHold": null,
    "backorder": null
  }
}
```

## Check a new order without saving it

`POST /v1/orders/preview`

Takes the same body as POST /v1/orders and returns what creating it would do: problems, the shipping options and their prices, the wallet hold and stock shortages. Nothing is saved, and it works while your account is on hold. It checks new orders only. The body is optional (an empty body is checked as an empty order).

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/orders/preview` |
| Permission | `orders:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | When you send a body | `application/json` |

### Request body

A JSON object. The body is optional: an empty body is treated as `{}`.

| Field | Type | Required | Description |
|---|---|---|---|
| `storeOrderNo` | string | No | Your store's order number, unique among your orders. Leave empty to use our order number. Default: `""`. Up to 100 characters, after spaces at both ends are removed. |
| `recipientName` | string | No | Recipient's full name. An order without it needs attention. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientCompany` | string | No | Company name, if any. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientPhone` | string | No | Recipient's phone number. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientEmail` | string | No | Recipient's email address. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `address1` | string | No | Street address. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `address2` | string | No | Apartment, suite or building, if any. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `city` | string | No | City. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `province` | string | No | State, province or region. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `postalCode` | string | No | Postal code. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `countryCode` | string | No | Two-letter country code, for example US. Default: `""`. |
| `channelId` | string | No | A shipping option from POST /v1/orders/preview (shippingOptions[].channelId). Leave empty to use your shipping preference for the country. Up to 64 characters. Default: `""`. |
| `buyerNote` | string | No | Note from your buyer, kept with the order. Line breaks are kept. Default: `""`. Up to 2,000 characters, after spaces at both ends are removed. |
| `lines` | array of objects | No | The items in the order. Up to 200 items. |
| `lines[].customerSku` | string | No | Your SKU for this item. When productId is empty we match it to a product through your SKU mappings. Default: `""`. Up to 100 characters, after spaces at both ends are removed. |
| `lines[].title` | string | No | Item name, for example from your store. Default: `""`. Up to 500 characters, after spaces at both ends are removed. |
| `lines[].qty` | integer | Yes | How many units. From 1 to 100,000. |
| `lines[].productId` | string | No | Our product id from GET /v1/products. Leave empty to match by customerSku. Up to 64 characters. Default: `""`. |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `willReserve` | boolean | true when the order has no problems: creating it reserves stock, holds the estimated shipping and handling fee in your wallet, and you can't change it afterwards. |
| `problems` | array of objects | Why the order would need attention; empty when there are none. Rely on `code`; `message` is English text that may change. |
| `problems[].code` | string | Problem code. See [Order problems](#order-problems). One of `NO_LINES`, `UNBOUND_LINE`, `MISSING_RECIPIENT`, `UNKNOWN_COUNTRY`, `NO_CHANNEL`, `CHANNEL_UNAVAILABLE`. |
| `problems[].message` | string | English text for display. It may change; rely on the code next to it. |
| `shippingChannelLabel` | string | The shipping option the order would use, in English. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `estimatedShippingCents` | integer or null | Estimated shipping for the option in `shippingChannelLabel`, in US cents; null when it can't be estimated. |
| `weightEstimated` | boolean | true when a product's weight is unknown and we estimated it. |
| `lines` | array of objects | One entry per line you sent, in the same order. |
| `lines[].productId` | string or null | The product the line matched; null when it doesn't match one of your products. |
| `lines[].productLabel` | string or null | Name of the matched product; null when the line doesn't match one of your products. |
| `shippingOptions` | array of objects or null | Shipping options for this order, cheapest first; null until the order has a country and at least one matched product. |
| `shippingOptions[].channelId` | string | Send this as channelId to use this shipping option. |
| `shippingOptions[].name` | string | Name of the shipping option in English. |
| `shippingOptions[].priceCents` | integer | Estimated shipping in US cents. |
| `shippingOptions[].priceMaxCents` | integer or null | Upper end of the estimate when the price depends on the postal code; null otherwise. |
| `shippingOptions[].transitLabel` | string | Delivery time in English, for example 7–12 days. |
| `shippingOptions[].chargeableG` | integer | Weight the price is based on, in grams. |
| `shippingOptions[].cheapest` | boolean | `true` for the cheapest option. |
| `shippingOptions[].fastest` | boolean | `true` for the fastest option. |
| `preferredShipping` | object or null | The option your shipping preference would pick when channelId is empty; null when no preference applies. |
| `preferredShipping.name` | string | Name of that shipping option. |
| `preferredShipping.priceCents` | integer or null | Its estimated price in US cents; null when it can't be priced. |
| `charges` | object | What creating the order would do to your wallet. See [Charges and your wallet](https://docs.rephut.com/developers/charges). |
| `charges.shippingCents` | integer or null | Estimated shipping in US cents; null when it can't be estimated. |
| `charges.handlingFeeCents` | integer | Handling fee in US cents. |
| `charges.holdCents` | integer or null | Held from your available balance when the order is created with no problems; null when nothing is held. |
| `charges.availableCents` | integer | Your available wallet balance now. |
| `charges.topUpCents` | integer | Top up at least this much to cover the hold; 0 when your balance is enough. |
| `shortages` | array of objects | Products with less available stock than ordered: the order waits for stock before packing. |
| `shortages[].productLabel` | string | Product name. |
| `shortages[].wantedQty` | integer | Quantity in the order. |
| `shortages[].availableQty` | integer | Quantity available now. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `order_product_not_allowed` | 422 | Choose products from My products. Other products can't be added to your orders here. |
| `orders_unavailable` | 422 | We can't take orders right now. Please contact your account manager. |
| `preference_channel_unavailable` | 422 | This shipping option is no longer available. Please choose another one. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/orders/preview' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "storeOrderNo": "1042",
  "recipientName": "Alex Morgan",
  "recipientCompany": "",
  "recipientPhone": "+1 555 0100",
  "recipientEmail": "alex@example.com",
  "address1": "12 Example Street",
  "address2": "Apt 4",
  "city": "Springfield",
  "province": "IL",
  "postalCode": "62701",
  "countryCode": "US",
  "channelId": "",
  "buyerNote": "Please leave at the door.",
  "lines": [
    {
      "customerSku": "TEE-BLK-M",
      "title": "Crew neck T-shirt, black, M",
      "qty": 2,
      "productId": ""
    }
  ]
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/orders/preview", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "storeOrderNo": "1042",
    "recipientName": "Alex Morgan",
    "recipientCompany": "",
    "recipientPhone": "+1 555 0100",
    "recipientEmail": "alex@example.com",
    "address1": "12 Example Street",
    "address2": "Apt 4",
    "city": "Springfield",
    "province": "IL",
    "postalCode": "62701",
    "countryCode": "US",
    "channelId": "",
    "buyerNote": "Please leave at the door.",
    "lines": [
      {
        "customerSku": "TEE-BLK-M",
        "title": "Crew neck T-shirt, black, M",
        "qty": 2,
        "productId": ""
      }
    ]
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/orders/preview",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    json={
        "storeOrderNo": "1042",
        "recipientName": "Alex Morgan",
        "recipientCompany": "",
        "recipientPhone": "+1 555 0100",
        "recipientEmail": "alex@example.com",
        "address1": "12 Example Street",
        "address2": "Apt 4",
        "city": "Springfield",
        "province": "IL",
        "postalCode": "62701",
        "countryCode": "US",
        "channelId": "",
        "buyerNote": "Please leave at the door.",
        "lines": [
            {
                "customerSku": "TEE-BLK-M",
                "title": "Crew neck T-shirt, black, M",
                "qty": 2,
                "productId": "",
            },
        ],
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "willReserve": true,
    "problems": [],
    "shippingChannelLabel": "US Standard",
    "currency": "USD",
    "estimatedShippingCents": 640,
    "weightEstimated": false,
    "lines": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "productLabel": "Cotton crew neck T-shirt (FB-10231-BLK-M)"
      }
    ],
    "shippingOptions": [
      {
        "channelId": "cm1ch0001usstd0000000001",
        "name": "US Standard",
        "priceCents": 640,
        "priceMaxCents": null,
        "transitLabel": "7–12 days",
        "chargeableG": 420,
        "cheapest": true,
        "fastest": false
      },
      {
        "channelId": "cm1ch0002usexp0000000002",
        "name": "US Express",
        "priceCents": 1380,
        "priceMaxCents": null,
        "transitLabel": "4–6 days",
        "chargeableG": 420,
        "cheapest": false,
        "fastest": true
      }
    ],
    "preferredShipping": {
      "name": "US Standard",
      "priceCents": 640
    },
    "charges": {
      "shippingCents": 640,
      "handlingFeeCents": 200,
      "holdCents": 840,
      "availableCents": 173160,
      "topUpCents": 0
    },
    "shortages": []
  }
}
```

## Create an order

`POST /v1/orders`

Saves the order like the portal's order form and returns it. Creating an order doesn't charge your wallet. When the order has no problems, we reserve its stock and hold the estimated shipping and handling fee from your available balance. When our warehouse weighs the parcel, the shipping and handling fee is charged to your wallet automatically. If auto purchase is on and an order is short of stock, we place and pay for a purchase order automatically, within the limits you set. An order with problems is saved with status NEEDS_ATTENTION; fix it with PATCH /v1/orders/{id}. Check it first with POST /v1/orders/preview. Send an Idempotency-Key so a retry can't create the order twice.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/orders` |
| Permission | `orders:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Required |
| Success | 201 Created |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | Yes | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

A JSON object. Fields not listed here are ignored.

| Field | Type | Required | Description |
|---|---|---|---|
| `storeOrderNo` | string | No | Your store's order number, unique among your orders. Leave empty to use our order number. Default: `""`. Up to 100 characters, after spaces at both ends are removed. |
| `recipientName` | string | No | Recipient's full name. An order without it needs attention. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientCompany` | string | No | Company name, if any. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientPhone` | string | No | Recipient's phone number. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientEmail` | string | No | Recipient's email address. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `address1` | string | No | Street address. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `address2` | string | No | Apartment, suite or building, if any. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `city` | string | No | City. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `province` | string | No | State, province or region. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `postalCode` | string | No | Postal code. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `countryCode` | string | No | Two-letter country code, for example US. Default: `""`. |
| `channelId` | string | No | A shipping option from POST /v1/orders/preview (shippingOptions[].channelId). Leave empty to use your shipping preference for the country. Up to 64 characters. Default: `""`. |
| `buyerNote` | string | No | Note from your buyer, kept with the order. Line breaks are kept. Default: `""`. Up to 2,000 characters, after spaces at both ends are removed. |
| `lines` | array of objects | No | The items in the order. Up to 200 items. |
| `lines[].customerSku` | string | No | Your SKU for this item. When productId is empty we match it to a product through your SKU mappings. Default: `""`. Up to 100 characters, after spaces at both ends are removed. |
| `lines[].title` | string | No | Item name, for example from your store. Default: `""`. Up to 500 characters, after spaces at both ends are removed. |
| `lines[].qty` | integer | Yes | How many units. From 1 to 100,000. |
| `lines[].productId` | string | No | Our product id from GET /v1/products. Leave empty to match by customerSku. Up to 64 characters. Default: `""`. |

### Response

`201` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Order id. |
| `number` | string | Our order number. |
| `storeOrderNo` | string | Your store's order number; empty when you didn't give one. |
| `status` | string | Order status. See [Order statuses](#order-statuses). One of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. For `NEEDS_ATTENTION` it names the first problem, for example "SKU not mapped". |
| `sourceLabel` | string | Where the order came from: `Store` (a connected store), `Imported` (a file import) or `Manual` (the portal form or the API). English text; it may change. |
| `createdAt` | string (date-time) | When the order was created. |
| `updatedAt` | string (date-time) | When the order last changed. Any edit through [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) changes it. |
| `cancelledAt` | string (date-time) or null | When the order was cancelled; null otherwise. |
| `recipient` | object | Who we ship to. |
| `recipient.name` | string | Recipient name. |
| `recipient.company` | string | Company; empty when none. |
| `recipient.phone` | string | Recipient phone number. |
| `recipient.email` | string | Recipient email address. |
| `recipient.address1` | string | Address line 1. |
| `recipient.address2` | string | Address line 2. |
| `recipient.city` | string | City. |
| `recipient.province` | string | State or province. |
| `recipient.postalCode` | string | Postal code. |
| `recipient.country` | string | Country in English. If we don't recognise it, the text the order has, or the code itself when the code is unknown; "—" when there is neither. |
| `recipient.countryCode` | string or null | Two-letter country code; null when we don't recognise the country. |
| `buyerNote` | string | Note from your buyer. |
| `lines` | array of objects | The items in the order. |
| `lines[].productId` | string or null | Our product id; null while the line is not matched to a product. |
| `lines[].productSku` | string or null | Our SKU of the matched product; null while the line isn't matched. |
| `lines[].productName` | string or null | Name of the matched product; null while the line isn't matched. |
| `lines[].customerSku` | string | Your SKU on this line. |
| `lines[].title` | string | Item name from your store or file. |
| `lines[].qty` | integer | Quantity. |
| `shippingChannelLabel` | string | The shipping option the order uses, in English; `Assigned by our team` when we chose it, `—` when none is set yet. |
| `shippedInStore` | boolean | `true` when you fulfilled the order yourself in your store, so we don't ship it. |
| `currency` | string | Currency of every amount in this order. Always `USD`. |
| `estimatedShippingCents` | integer or null | Estimated shipping in US cents; null when it can't be estimated yet, and when `shippedInStore` is `true`. |
| `weightEstimated` | boolean | `true` when a product's weight is unknown and the estimate uses an assumed weight. Only before the parcel is weighed; `false` afterwards. |
| `problems` | array of objects | Why the order needs attention; empty otherwise. Rely on `code`; `message` is English text that may change. |
| `problems[].code` | string | Problem code. See [Order problems](#order-problems). One of `NO_LINES`, `UNBOUND_LINE`, `MISSING_RECIPIENT`, `UNKNOWN_COUNTRY`, `NO_CHANNEL`, `CHANNEL_UNAVAILABLE`. |
| `problems[].message` | string | English text for display. It may change; rely on the code next to it. |
| `fulfilment` | object or null | What our warehouse did with the parcel. Present when the status is `RESERVED`, `WEIGHED` or `SHIPPED`; null otherwise. |
| `fulfilment.trackingNo` | string | Tracking number; empty until the parcel ships. |
| `fulfilment.trackingUrl` | string or null | Link to track the parcel; null when we have none. |
| `fulfilment.shippedAt` | string (date-time) or null | When the parcel shipped; null until then. |
| `fulfilment.actualWeightG` | integer or null | Weighed parcel weight in grams; null until weighed. |
| `fulfilment.freightCents` | integer or null | Shipping charged, in US cents; null until charged. |
| `fulfilment.handlingFeeCents` | integer or null | Handling fee charged, in US cents; null until charged. |
| `fulfilment.surchargeCents` | integer or null | Extra shipping charged later (for example a carrier adjustment), in US cents; null when none. |
| `fulfilment.totalChargedCents` | integer or null | Everything charged for this order, in US cents; null until charged. |
| `payment` | object or null | Shipping charge waiting for wallet funds; null when nothing is due. |
| `payment.freightCents` | integer | Shipping fee waiting to be paid, in US cents. |
| `payment.handlingFeeCents` | integer | Handling fee waiting to be paid, in US cents. |
| `payment.dueCents` | integer | Total waiting to be paid, in US cents. |
| `payment.availableCents` | integer | Your available balance plus the amount already held for this order, in US cents. |
| `payment.topUpCents` | integer | At least this much to top up. |
| `shippingHold` | object or null | The estimated shipping and handling fee held from your available balance while the order waits to ship; null when nothing is held. See [Charges and your wallet](https://docs.rephut.com/developers/charges). |
| `shippingHold.heldCents` | integer | Amount held, in US cents. |
| `shippingHold.topUpCents` | integer | Top up at least this much when your balance doesn't cover the hold; 0 when it does. |
| `backorder` | object or null | What the order is waiting for when some products are short; null otherwise. |
| `backorder.lines` | array of objects | Products short for this order. |
| `backorder.lines[].productSku` | string | Our SKU. |
| `backorder.lines[].productName` | string | Product name. |
| `backorder.lines[].orderedQty` | integer | Quantity ordered. |
| `backorder.lines[].waitingQty` | integer | Quantity still waiting for stock. |
| `backorder.purchaseOrders` | array of objects | Purchase orders that bring the missing stock. |
| `backorder.purchaseOrders[].id` | string | Purchase order id. Fetch it with [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order). |
| `backorder.purchaseOrders[].number` | string | Purchase order number. |
| `backorder.purchaseOrders[].statusLabel` | string | English text for display. It may change; rely on the code next to it. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `idempotency_key_required` | 400 | This request needs an Idempotency-Key header. |
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `store_order_no_taken` | 409 | You already have an order with this store order number. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `order_product_not_allowed` | 422 | Choose products from My products. Other products can't be added to your orders here. |
| `orders_unavailable` | 422 | We can't take orders right now. Please contact your account manager. |
| `preference_channel_unavailable` | 422 | This shipping option is no longer available. Please choose another one. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/orders' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: 5d0f6c1e-8a4b-4c1d-9b7e-2f3a4b5c6d7e' \
  -d '{
  "storeOrderNo": "1042",
  "recipientName": "Alex Morgan",
  "recipientCompany": "",
  "recipientPhone": "+1 555 0100",
  "recipientEmail": "alex@example.com",
  "address1": "12 Example Street",
  "address2": "Apt 4",
  "city": "Springfield",
  "province": "IL",
  "postalCode": "62701",
  "countryCode": "US",
  "channelId": "",
  "buyerNote": "Please leave at the door.",
  "lines": [
    {
      "customerSku": "TEE-BLK-M",
      "title": "Crew neck T-shirt, black, M",
      "qty": 2,
      "productId": ""
    }
  ]
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "5d0f6c1e-8a4b-4c1d-9b7e-2f3a4b5c6d7e",
  },
  body: JSON.stringify({
    "storeOrderNo": "1042",
    "recipientName": "Alex Morgan",
    "recipientCompany": "",
    "recipientPhone": "+1 555 0100",
    "recipientEmail": "alex@example.com",
    "address1": "12 Example Street",
    "address2": "Apt 4",
    "city": "Springfield",
    "province": "IL",
    "postalCode": "62701",
    "countryCode": "US",
    "channelId": "",
    "buyerNote": "Please leave at the door.",
    "lines": [
      {
        "customerSku": "TEE-BLK-M",
        "title": "Crew neck T-shirt, black, M",
        "qty": 2,
        "productId": ""
      }
    ]
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/orders",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "5d0f6c1e-8a4b-4c1d-9b7e-2f3a4b5c6d7e",
    },
    json={
        "storeOrderNo": "1042",
        "recipientName": "Alex Morgan",
        "recipientCompany": "",
        "recipientPhone": "+1 555 0100",
        "recipientEmail": "alex@example.com",
        "address1": "12 Example Street",
        "address2": "Apt 4",
        "city": "Springfield",
        "province": "IL",
        "postalCode": "62701",
        "countryCode": "US",
        "channelId": "",
        "buyerNote": "Please leave at the door.",
        "lines": [
            {
                "customerSku": "TEE-BLK-M",
                "title": "Crew neck T-shirt, black, M",
                "qty": 2,
                "productId": "",
            },
        ],
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=201
{
  "success": true,
  "data": {
    "id": "cm3o7rd0e0001h2j3k4l5m6n",
    "number": "D2611090012",
    "storeOrderNo": "1042",
    "status": "READY",
    "statusLabel": "Ready for fulfilment",
    "sourceLabel": "Manual",
    "createdAt": "2026-11-09T02:00:00.000Z",
    "updatedAt": "2026-11-09T02:00:00.000Z",
    "cancelledAt": null,
    "recipient": {
      "name": "Alex Morgan",
      "company": "",
      "phone": "+1 555 0100",
      "email": "alex@example.com",
      "address1": "12 Example Street",
      "address2": "Apt 4",
      "city": "Springfield",
      "province": "IL",
      "postalCode": "62701",
      "country": "United States",
      "countryCode": "US"
    },
    "buyerNote": "Please leave at the door.",
    "lines": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "productSku": "FB-10231-BLK-M",
        "productName": "Cotton crew neck T-shirt",
        "customerSku": "TEE-BLK-M",
        "title": "Crew neck T-shirt, black, M",
        "qty": 2
      }
    ],
    "shippingChannelLabel": "US Standard",
    "shippedInStore": false,
    "currency": "USD",
    "estimatedShippingCents": 640,
    "weightEstimated": false,
    "problems": [],
    "fulfilment": null,
    "payment": null,
    "shippingHold": null,
    "backorder": null
  }
}
```

## Change an order that needs attention

`PATCH /v1/orders/{id}`

Replaces the whole order with the body, like saving the portal's order form: send every field and every line, as for POST /v1/orders; fields you leave out are cleared. Only orders with status NEEDS_ATTENTION can be changed (otherwise 409 order_not_editable). Orders from a connected store keep the store's order number. Creating an order doesn't charge your wallet. When the order has no problems, we reserve its stock and hold the estimated shipping and handling fee from your available balance.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/orders/{id}` |
| Permission | `orders:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Optional, recommended |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Order id. An id that doesn't exist or isn't yours returns 404 `order_not_found`; an id that isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

A JSON object. Fields not listed here are ignored.

| Field | Type | Required | Description |
|---|---|---|---|
| `storeOrderNo` | string | No | Your store's order number, unique among your orders. Leave empty to use our order number. Default: `""`. Up to 100 characters, after spaces at both ends are removed. |
| `recipientName` | string | No | Recipient's full name. An order without it needs attention. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientCompany` | string | No | Company name, if any. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientPhone` | string | No | Recipient's phone number. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `recipientEmail` | string | No | Recipient's email address. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `address1` | string | No | Street address. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `address2` | string | No | Apartment, suite or building, if any. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `city` | string | No | City. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `province` | string | No | State, province or region. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `postalCode` | string | No | Postal code. Default: `""`. Up to 200 characters, after spaces at both ends are removed. |
| `countryCode` | string | No | Two-letter country code, for example US. Default: `""`. |
| `channelId` | string | No | A shipping option from POST /v1/orders/preview (shippingOptions[].channelId). Leave empty to use your shipping preference for the country. Up to 64 characters. Default: `""`. |
| `buyerNote` | string | No | Note from your buyer, kept with the order. Line breaks are kept. Default: `""`. Up to 2,000 characters, after spaces at both ends are removed. |
| `lines` | array of objects | No | The items in the order. Up to 200 items. |
| `lines[].customerSku` | string | No | Your SKU for this item. When productId is empty we match it to a product through your SKU mappings. Default: `""`. Up to 100 characters, after spaces at both ends are removed. |
| `lines[].title` | string | No | Item name, for example from your store. Default: `""`. Up to 500 characters, after spaces at both ends are removed. |
| `lines[].qty` | integer | Yes | How many units. From 1 to 100,000. |
| `lines[].productId` | string | No | Our product id from GET /v1/products. Leave empty to match by customerSku. Up to 64 characters. Default: `""`. |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Order id. |
| `number` | string | Our order number. |
| `storeOrderNo` | string | Your store's order number; empty when you didn't give one. |
| `status` | string | Order status. See [Order statuses](#order-statuses). One of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. For `NEEDS_ATTENTION` it names the first problem, for example "SKU not mapped". |
| `sourceLabel` | string | Where the order came from: `Store` (a connected store), `Imported` (a file import) or `Manual` (the portal form or the API). English text; it may change. |
| `createdAt` | string (date-time) | When the order was created. |
| `updatedAt` | string (date-time) | When the order last changed. Any edit through [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) changes it. |
| `cancelledAt` | string (date-time) or null | When the order was cancelled; null otherwise. |
| `recipient` | object | Who we ship to. |
| `recipient.name` | string | Recipient name. |
| `recipient.company` | string | Company; empty when none. |
| `recipient.phone` | string | Recipient phone number. |
| `recipient.email` | string | Recipient email address. |
| `recipient.address1` | string | Address line 1. |
| `recipient.address2` | string | Address line 2. |
| `recipient.city` | string | City. |
| `recipient.province` | string | State or province. |
| `recipient.postalCode` | string | Postal code. |
| `recipient.country` | string | Country in English. If we don't recognise it, the text the order has, or the code itself when the code is unknown; "—" when there is neither. |
| `recipient.countryCode` | string or null | Two-letter country code; null when we don't recognise the country. |
| `buyerNote` | string | Note from your buyer. |
| `lines` | array of objects | The items in the order. |
| `lines[].productId` | string or null | Our product id; null while the line is not matched to a product. |
| `lines[].productSku` | string or null | Our SKU of the matched product; null while the line isn't matched. |
| `lines[].productName` | string or null | Name of the matched product; null while the line isn't matched. |
| `lines[].customerSku` | string | Your SKU on this line. |
| `lines[].title` | string | Item name from your store or file. |
| `lines[].qty` | integer | Quantity. |
| `shippingChannelLabel` | string | The shipping option the order uses, in English; `Assigned by our team` when we chose it, `—` when none is set yet. |
| `shippedInStore` | boolean | `true` when you fulfilled the order yourself in your store, so we don't ship it. |
| `currency` | string | Currency of every amount in this order. Always `USD`. |
| `estimatedShippingCents` | integer or null | Estimated shipping in US cents; null when it can't be estimated yet, and when `shippedInStore` is `true`. |
| `weightEstimated` | boolean | `true` when a product's weight is unknown and the estimate uses an assumed weight. Only before the parcel is weighed; `false` afterwards. |
| `problems` | array of objects | Why the order needs attention; empty otherwise. Rely on `code`; `message` is English text that may change. |
| `problems[].code` | string | Problem code. See [Order problems](#order-problems). One of `NO_LINES`, `UNBOUND_LINE`, `MISSING_RECIPIENT`, `UNKNOWN_COUNTRY`, `NO_CHANNEL`, `CHANNEL_UNAVAILABLE`. |
| `problems[].message` | string | English text for display. It may change; rely on the code next to it. |
| `fulfilment` | object or null | What our warehouse did with the parcel. Present when the status is `RESERVED`, `WEIGHED` or `SHIPPED`; null otherwise. |
| `fulfilment.trackingNo` | string | Tracking number; empty until the parcel ships. |
| `fulfilment.trackingUrl` | string or null | Link to track the parcel; null when we have none. |
| `fulfilment.shippedAt` | string (date-time) or null | When the parcel shipped; null until then. |
| `fulfilment.actualWeightG` | integer or null | Weighed parcel weight in grams; null until weighed. |
| `fulfilment.freightCents` | integer or null | Shipping charged, in US cents; null until charged. |
| `fulfilment.handlingFeeCents` | integer or null | Handling fee charged, in US cents; null until charged. |
| `fulfilment.surchargeCents` | integer or null | Extra shipping charged later (for example a carrier adjustment), in US cents; null when none. |
| `fulfilment.totalChargedCents` | integer or null | Everything charged for this order, in US cents; null until charged. |
| `payment` | object or null | Shipping charge waiting for wallet funds; null when nothing is due. |
| `payment.freightCents` | integer | Shipping fee waiting to be paid, in US cents. |
| `payment.handlingFeeCents` | integer | Handling fee waiting to be paid, in US cents. |
| `payment.dueCents` | integer | Total waiting to be paid, in US cents. |
| `payment.availableCents` | integer | Your available balance plus the amount already held for this order, in US cents. |
| `payment.topUpCents` | integer | At least this much to top up. |
| `shippingHold` | object or null | The estimated shipping and handling fee held from your available balance while the order waits to ship; null when nothing is held. See [Charges and your wallet](https://docs.rephut.com/developers/charges). |
| `shippingHold.heldCents` | integer | Amount held, in US cents. |
| `shippingHold.topUpCents` | integer | Top up at least this much when your balance doesn't cover the hold; 0 when it does. |
| `backorder` | object or null | What the order is waiting for when some products are short; null otherwise. |
| `backorder.lines` | array of objects | Products short for this order. |
| `backorder.lines[].productSku` | string | Our SKU. |
| `backorder.lines[].productName` | string | Product name. |
| `backorder.lines[].orderedQty` | integer | Quantity ordered. |
| `backorder.lines[].waitingQty` | integer | Quantity still waiting for stock. |
| `backorder.purchaseOrders` | array of objects | Purchase orders that bring the missing stock. |
| `backorder.purchaseOrders[].id` | string | Purchase order id. Fetch it with [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order). |
| `backorder.purchaseOrders[].number` | string | Purchase order number. |
| `backorder.purchaseOrders[].statusLabel` | string | English text for display. It may change; rely on the code next to it. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `order_not_found` | 404 | This order could not be found. |
| `order_not_editable` | 409 | This order can no longer be changed or cancelled here. Refresh the page to see its latest status. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `store_order_no_locked` | 409 | Orders from your store keep the store's order number, so it can't be changed here. |
| `store_order_no_taken` | 409 | You already have an order with this store order number. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `order_product_not_allowed` | 422 | Choose products from My products. Other products can't be added to your orders here. |
| `orders_unavailable` | 422 | We can't take orders right now. Please contact your account manager. |
| `preference_channel_unavailable` | 422 | This shipping option is no longer available. Please choose another one. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X PATCH 'https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: a3c9e1f2-7b6d-4e85-8f10-3c2b1a0d9e8f' \
  -d '{
  "storeOrderNo": "1042",
  "recipientName": "Alex Morgan",
  "recipientCompany": "",
  "recipientPhone": "+1 555 0100",
  "recipientEmail": "alex@example.com",
  "address1": "12 Example Street",
  "address2": "Apt 4",
  "city": "Springfield",
  "province": "IL",
  "postalCode": "62701",
  "countryCode": "US",
  "channelId": "",
  "buyerNote": "Please leave at the door.",
  "lines": [
    {
      "customerSku": "TEE-BLK-M",
      "title": "Crew neck T-shirt, black, M",
      "qty": 2,
      "productId": ""
    }
  ]
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "a3c9e1f2-7b6d-4e85-8f10-3c2b1a0d9e8f",
  },
  body: JSON.stringify({
    "storeOrderNo": "1042",
    "recipientName": "Alex Morgan",
    "recipientCompany": "",
    "recipientPhone": "+1 555 0100",
    "recipientEmail": "alex@example.com",
    "address1": "12 Example Street",
    "address2": "Apt 4",
    "city": "Springfield",
    "province": "IL",
    "postalCode": "62701",
    "countryCode": "US",
    "channelId": "",
    "buyerNote": "Please leave at the door.",
    "lines": [
      {
        "customerSku": "TEE-BLK-M",
        "title": "Crew neck T-shirt, black, M",
        "qty": 2,
        "productId": ""
      }
    ]
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.patch(
    "https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "a3c9e1f2-7b6d-4e85-8f10-3c2b1a0d9e8f",
    },
    json={
        "storeOrderNo": "1042",
        "recipientName": "Alex Morgan",
        "recipientCompany": "",
        "recipientPhone": "+1 555 0100",
        "recipientEmail": "alex@example.com",
        "address1": "12 Example Street",
        "address2": "Apt 4",
        "city": "Springfield",
        "province": "IL",
        "postalCode": "62701",
        "countryCode": "US",
        "channelId": "",
        "buyerNote": "Please leave at the door.",
        "lines": [
            {
                "customerSku": "TEE-BLK-M",
                "title": "Crew neck T-shirt, black, M",
                "qty": 2,
                "productId": "",
            },
        ],
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3o7rd0e0001h2j3k4l5m6n",
    "number": "D2611090012",
    "storeOrderNo": "1042",
    "status": "READY",
    "statusLabel": "Ready for fulfilment",
    "sourceLabel": "Manual",
    "createdAt": "2026-11-09T02:00:00.000Z",
    "updatedAt": "2026-11-09T02:30:00.000Z",
    "cancelledAt": null,
    "recipient": {
      "name": "Alex Morgan",
      "company": "",
      "phone": "+1 555 0100",
      "email": "alex@example.com",
      "address1": "12 Example Street",
      "address2": "Apt 4",
      "city": "Springfield",
      "province": "IL",
      "postalCode": "62701",
      "country": "United States",
      "countryCode": "US"
    },
    "buyerNote": "Please leave at the door.",
    "lines": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "productSku": "FB-10231-BLK-M",
        "productName": "Cotton crew neck T-shirt",
        "customerSku": "TEE-BLK-M",
        "title": "Crew neck T-shirt, black, M",
        "qty": 2
      }
    ],
    "shippingChannelLabel": "US Standard",
    "shippedInStore": false,
    "currency": "USD",
    "estimatedShippingCents": 640,
    "weightEstimated": false,
    "problems": [],
    "fulfilment": null,
    "payment": null,
    "shippingHold": null,
    "backorder": null
  }
}
```

## Cancel an order that needs attention

`POST /v1/orders/{id}/cancel`

Only orders with status NEEDS_ATTENTION can be cancelled here (otherwise 409 order_not_editable); for other orders contact your account manager. The body is optional.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/orders/{id}/cancel` |
| Permission | `orders:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Optional, recommended |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Order id. An id that doesn't exist or isn't yours returns 404 `order_not_found`; an id that isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | When you send a body | `application/json` |
| `Idempotency-Key` | No | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

A JSON object. The body is optional: an empty body is treated as `{}`.

| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | string | No | Why you cancel the order, up to 500 characters. Optional; our team can see it. Default: `""`. |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Order id. |
| `number` | string | Our order number. |
| `storeOrderNo` | string | Your store's order number; empty when you didn't give one. |
| `status` | string | Order status. See [Order statuses](#order-statuses). One of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. For `NEEDS_ATTENTION` it names the first problem, for example "SKU not mapped". |
| `sourceLabel` | string | Where the order came from: `Store` (a connected store), `Imported` (a file import) or `Manual` (the portal form or the API). English text; it may change. |
| `createdAt` | string (date-time) | When the order was created. |
| `updatedAt` | string (date-time) | When the order last changed. Any edit through [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention) changes it. |
| `cancelledAt` | string (date-time) or null | When the order was cancelled; null otherwise. |
| `recipient` | object | Who we ship to. |
| `recipient.name` | string | Recipient name. |
| `recipient.company` | string | Company; empty when none. |
| `recipient.phone` | string | Recipient phone number. |
| `recipient.email` | string | Recipient email address. |
| `recipient.address1` | string | Address line 1. |
| `recipient.address2` | string | Address line 2. |
| `recipient.city` | string | City. |
| `recipient.province` | string | State or province. |
| `recipient.postalCode` | string | Postal code. |
| `recipient.country` | string | Country in English. If we don't recognise it, the text the order has, or the code itself when the code is unknown; "—" when there is neither. |
| `recipient.countryCode` | string or null | Two-letter country code; null when we don't recognise the country. |
| `buyerNote` | string | Note from your buyer. |
| `lines` | array of objects | The items in the order. |
| `lines[].productId` | string or null | Our product id; null while the line is not matched to a product. |
| `lines[].productSku` | string or null | Our SKU of the matched product; null while the line isn't matched. |
| `lines[].productName` | string or null | Name of the matched product; null while the line isn't matched. |
| `lines[].customerSku` | string | Your SKU on this line. |
| `lines[].title` | string | Item name from your store or file. |
| `lines[].qty` | integer | Quantity. |
| `shippingChannelLabel` | string | The shipping option the order uses, in English; `Assigned by our team` when we chose it, `—` when none is set yet. |
| `shippedInStore` | boolean | `true` when you fulfilled the order yourself in your store, so we don't ship it. |
| `currency` | string | Currency of every amount in this order. Always `USD`. |
| `estimatedShippingCents` | integer or null | Estimated shipping in US cents; null when it can't be estimated yet, and when `shippedInStore` is `true`. |
| `weightEstimated` | boolean | `true` when a product's weight is unknown and the estimate uses an assumed weight. Only before the parcel is weighed; `false` afterwards. |
| `problems` | array of objects | Why the order needs attention; empty otherwise. Rely on `code`; `message` is English text that may change. |
| `problems[].code` | string | Problem code. See [Order problems](#order-problems). One of `NO_LINES`, `UNBOUND_LINE`, `MISSING_RECIPIENT`, `UNKNOWN_COUNTRY`, `NO_CHANNEL`, `CHANNEL_UNAVAILABLE`. |
| `problems[].message` | string | English text for display. It may change; rely on the code next to it. |
| `fulfilment` | object or null | What our warehouse did with the parcel. Present when the status is `RESERVED`, `WEIGHED` or `SHIPPED`; null otherwise. |
| `fulfilment.trackingNo` | string | Tracking number; empty until the parcel ships. |
| `fulfilment.trackingUrl` | string or null | Link to track the parcel; null when we have none. |
| `fulfilment.shippedAt` | string (date-time) or null | When the parcel shipped; null until then. |
| `fulfilment.actualWeightG` | integer or null | Weighed parcel weight in grams; null until weighed. |
| `fulfilment.freightCents` | integer or null | Shipping charged, in US cents; null until charged. |
| `fulfilment.handlingFeeCents` | integer or null | Handling fee charged, in US cents; null until charged. |
| `fulfilment.surchargeCents` | integer or null | Extra shipping charged later (for example a carrier adjustment), in US cents; null when none. |
| `fulfilment.totalChargedCents` | integer or null | Everything charged for this order, in US cents; null until charged. |
| `payment` | object or null | Shipping charge waiting for wallet funds; null when nothing is due. |
| `payment.freightCents` | integer | Shipping fee waiting to be paid, in US cents. |
| `payment.handlingFeeCents` | integer | Handling fee waiting to be paid, in US cents. |
| `payment.dueCents` | integer | Total waiting to be paid, in US cents. |
| `payment.availableCents` | integer | Your available balance plus the amount already held for this order, in US cents. |
| `payment.topUpCents` | integer | At least this much to top up. |
| `shippingHold` | object or null | The estimated shipping and handling fee held from your available balance while the order waits to ship; null when nothing is held. See [Charges and your wallet](https://docs.rephut.com/developers/charges). |
| `shippingHold.heldCents` | integer | Amount held, in US cents. |
| `shippingHold.topUpCents` | integer | Top up at least this much when your balance doesn't cover the hold; 0 when it does. |
| `backorder` | object or null | What the order is waiting for when some products are short; null otherwise. |
| `backorder.lines` | array of objects | Products short for this order. |
| `backorder.lines[].productSku` | string | Our SKU. |
| `backorder.lines[].productName` | string | Product name. |
| `backorder.lines[].orderedQty` | integer | Quantity ordered. |
| `backorder.lines[].waitingQty` | integer | Quantity still waiting for stock. |
| `backorder.purchaseOrders` | array of objects | Purchase orders that bring the missing stock. |
| `backorder.purchaseOrders[].id` | string | Purchase order id. Fetch it with [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order). |
| `backorder.purchaseOrders[].number` | string | Purchase order number. |
| `backorder.purchaseOrders[].statusLabel` | string | English text for display. It may change; rely on the code next to it. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `order_not_found` | 404 | This order could not be found. |
| `order_not_editable` | 409 | This order can no longer be changed or cancelled here. Refresh the page to see its latest status. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n/cancel' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: 0b8e4d7a-5c13-4f92-86a1-d3e7f9c2b410' \
  -d '{
  "reason": "The buyer cancelled in our store."
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "0b8e4d7a-5c13-4f92-86a1-d3e7f9c2b410",
  },
  body: JSON.stringify({
    "reason": "The buyer cancelled in our store."
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/orders/cm3o7rd0e0001h2j3k4l5m6n/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "0b8e4d7a-5c13-4f92-86a1-d3e7f9c2b410",
    },
    json={
        "reason": "The buyer cancelled in our store.",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3o7rd0e0001h2j3k4l5m6n",
    "number": "D2611090012",
    "storeOrderNo": "1042",
    "status": "CANCELLED",
    "statusLabel": "Cancelled",
    "sourceLabel": "Manual",
    "createdAt": "2026-11-09T02:00:00.000Z",
    "updatedAt": "2026-11-09T03:00:00.000Z",
    "cancelledAt": "2026-11-09T03:00:00.000Z",
    "recipient": {
      "name": "Alex Morgan",
      "company": "",
      "phone": "+1 555 0100",
      "email": "alex@example.com",
      "address1": "12 Example Street",
      "address2": "Apt 4",
      "city": "Springfield",
      "province": "IL",
      "postalCode": "62701",
      "country": "United States",
      "countryCode": "US"
    },
    "buyerNote": "Please leave at the door.",
    "lines": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "productSku": "FB-10231-BLK-M",
        "productName": "Cotton crew neck T-shirt",
        "customerSku": "TEE-BLK-M",
        "title": "Crew neck T-shirt, black, M",
        "qty": 2
      }
    ],
    "shippingChannelLabel": "US Standard",
    "shippedInStore": false,
    "currency": "USD",
    "estimatedShippingCents": 640,
    "weightEstimated": false,
    "problems": [],
    "fulfilment": null,
    "payment": null,
    "shippingHold": null,
    "backorder": null
  }
}
```

---

Source: https://docs.rephut.com/developers/reference/purchase-orders

# Purchase orders

A purchase order is what we buy for you from a seller: from a reorder or sourcing request, from auto purchase when orders are short of stock, or one you placed yourself from Search in the portal. When its goods arrive and are checked, they become stock in your inventory.

You can read purchase orders here. Purchase orders from auto purchase are paid from your wallet automatically when your available balance covers them; otherwise they wait and are paid automatically after a top-up ([Charges and your wallet](https://docs.rephut.com/developers/charges)). Pay all other purchase orders in the portal; the API can't pay yet. Webhook `purchase_order.status_changed` reports every status change. The list is sorted newest first and includes cancelled purchase orders. There is no `updatedSince` here: use webhooks and GET, or read the first pages again to find new ones (the list is newest first). See [Incremental sync](https://docs.rephut.com/developers/incremental-sync).

## Purchase order statuses

| Value | Meaning |
|---|---|
| `AWAITING_PAYMENT` | Waiting for your payment. Pay purchase orders in the portal. |
| `DEPOSIT_PAID` | We received a deposit; the rest is due later. |
| `PAID` | Paid in full; we are about to buy the goods. |
| `PURCHASING` | We are buying the goods from the seller. The statuses from here to `ARRIVED` say how far the goods have got, not whether you have paid; payment may still be partly or fully due. |
| `ORDERED` | Ordered from the seller (shown as Purchasing in the portal). |
| `IN_TRANSIT` | On the way to our warehouse. |
| `PARTIALLY_ARRIVED` | Some of the goods arrived at our warehouse. |
| `ARRIVED` | All goods arrived at our warehouse. |
| `STORED` | All goods are in stock in our warehouse (or settled as short); some payment is still due. |
| `COMPLETED` | Paid in full and all goods are in stock (or settled as short). |
| `CANCELLED` | Cancelled. `cancelledAt` says when. |

## List purchase orders

`GET /v1/purchase-orders`

All your purchase orders, including cancelled ones. Newest first.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/purchase-orders` |
| Permission | `purchase_orders:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `id` | string | Purchase order id. |
| `number` | string | Our purchase order number. |
| `status` | string | Purchase order status. See [Purchase order statuses](#purchase-order-statuses). One of `AWAITING_PAYMENT`, `DEPOSIT_PAID`, `PAID`, `PURCHASING`, `ORDERED`, `IN_TRANSIT`, `PARTIALLY_ARRIVED`, `ARRIVED`, `STORED`, `COMPLETED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `itemCount` | integer | Number of products on the purchase order. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `receivableCents` | integer | What you pay: the total minus short-shipped items. |
| `paidCents` | integer | Paid so far minus refunds, in US cents. |
| `dueCents` | integer | Still to pay, in US cents; 0 when the purchase order is cancelled. |
| `createdAt` | string (date-time) | When the purchase order was created. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/purchase-orders?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/purchase-orders?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/purchase-orders?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "id": "cm3q1po0r0001der5t6y7u8i",
      "number": "PO2611040003",
      "status": "IN_TRANSIT",
      "statusLabel": "On the way to warehouse",
      "itemCount": 1,
      "currency": "USD",
      "receivableCents": 78500,
      "paidCents": 78500,
      "dueCents": 0,
      "createdAt": "2026-11-04T05:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

## Get a purchase order

`GET /v1/purchase-orders/{id}`

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/purchase-orders/{id}` |
| Permission | `purchase_orders:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Purchase order id, from [`GET /v1/purchase-orders`](https://docs.rephut.com/developers/reference/purchase-orders#list-purchase-orders). An id that doesn't exist, isn't yours or isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Purchase order id. |
| `number` | string | Our purchase order number. |
| `status` | string | Purchase order status. See [Purchase order statuses](#purchase-order-statuses). One of `AWAITING_PAYMENT`, `DEPOSIT_PAID`, `PAID`, `PURCHASING`, `ORDERED`, `IN_TRANSIT`, `PARTIALLY_ARRIVED`, `ARRIVED`, `STORED`, `COMPLETED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `createdAt` | string (date-time) | When the purchase order was created. |
| `cancelledAt` | string (date-time) or null | When it was cancelled; null otherwise. |
| `paymentMethodName` | string or null | The payment method set for this purchase order; null when none. |
| `note` | string | Note on the purchase order. |
| `placedViaSearch` | boolean | `true` when you placed it yourself from Search in the portal. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `items` | array of objects | Products on the purchase order. |
| `items[].productId` | string | Our product id. |
| `items[].sku` | string | Our SKU. |
| `items[].name` | string | Product name in English. |
| `items[].attributes` | string | Variant details in English. |
| `items[].customerSku` | string | Your SKU for the product when it is mapped; empty otherwise. |
| `items[].qty` | integer | Quantity on the purchase order. |
| `items[].unitPriceCents` | integer | Unit price in US cents. |
| `items[].amountCents` | integer | Line amount in US cents. |
| `items[].orderedQty` | integer | Quantity we have ordered from the seller. |
| `items[].inWarehouseQty` | integer | Quantity received in our warehouse in good condition. |
| `items[].shortQty` | integer | Short-shipped or refunded by the seller. |
| `charges` | array of objects | Other charges on the purchase order, such as domestic shipping. |
| `charges[].label` | string | What the charge is for. |
| `charges[].amountCents` | integer | Amount in US cents. |
| `totalCents` | integer | Goods plus charges, in US cents. |
| `shortageCents` | integer | Value of short-shipped or refunded items, in US cents. |
| `receivableCents` | integer | What you pay: `totalCents` minus `shortageCents`. |
| `paidCents` | integer | Paid so far minus refunds, in US cents. |
| `dueCents` | integer | Still to pay, in US cents; 0 when the purchase order is cancelled. |
| `payments` | array of objects | Payments received. |
| `payments[].paidOn` | string (date) | The day of the payment (YYYY-MM-DD, China time). |
| `payments[].amountCents` | integer | Amount in US cents. |
| `payments[].methodLabel` | string | Payment method. |
| `refunds` | array of objects | Refunds to you. |
| `refunds[].label` | string | What was refunded. |
| `refunds[].amountCents` | integer | Amount in US cents. |
| `refunds[].refundedAt` | string (date-time) | When it was refunded. |
| `paymentInstructions` | array of objects | How to pay; empty when nothing is due. |
| `paymentInstructions[].name` | string | Payment method name. |
| `paymentInstructions[].instructions` | string | How to pay with this method. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/purchase-orders/cm3q1po0r0001der5t6y7u8i' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/purchase-orders/cm3q1po0r0001der5t6y7u8i", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/purchase-orders/cm3q1po0r0001der5t6y7u8i",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3q1po0r0001der5t6y7u8i",
    "number": "PO2611040003",
    "status": "IN_TRANSIT",
    "statusLabel": "On the way to warehouse",
    "createdAt": "2026-11-04T05:00:00.000Z",
    "cancelledAt": null,
    "paymentMethodName": "Wallet",
    "note": "",
    "placedViaSearch": false,
    "currency": "USD",
    "items": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "sku": "FB-10231-BLK-M",
        "name": "Cotton crew neck T-shirt",
        "attributes": "Black / M",
        "customerSku": "TEE-BLK-M",
        "qty": 200,
        "unitPriceCents": 385,
        "amountCents": 77000,
        "orderedQty": 200,
        "inWarehouseQty": 0,
        "shortQty": 0
      }
    ],
    "charges": [
      {
        "label": "Domestic shipping",
        "amountCents": 1500
      }
    ],
    "totalCents": 78500,
    "shortageCents": 0,
    "receivableCents": 78500,
    "paidCents": 78500,
    "dueCents": 0,
    "payments": [
      {
        "paidOn": "2026-11-04",
        "amountCents": 78500,
        "methodLabel": "Wallet balance"
      }
    ],
    "refunds": [],
    "paymentInstructions": []
  }
}
```

---

Source: https://docs.rephut.com/developers/reference/shipments

# Shipments

A shipment sends goods from your stock in our warehouse in bulk: to an address (`WHOLESALE`) or to an Amazon warehouse (`FBA`). Dropship orders to your buyers are separate: see [Orders](https://docs.rephut.com/developers/reference/orders).

There is no `updatedSince` for shipments: use webhooks and GET, or read the first pages again to find new ones (the list is newest first). See [Incremental sync](https://docs.rephut.com/developers/incremental-sync).

## How a shipment works

1. Optionally, check shipping options and prices with [`POST /v1/shipments/estimate`](https://docs.rephut.com/developers/reference/shipments#estimate-shipping-for-a-shipment-from-your-stock). Nothing is saved.
2. Ask for the shipment with [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock) and an `Idempotency-Key`. The stock is set aside and the shipment is `DRAFT`. Until we send the quote you can cancel it with [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested).
3. We pack it, set the shipping and send you the freight quote: the status becomes `PENDING_CONFIRMATION` (webhook `shipment.status_changed`).
4. Read it with [`GET /v1/shipments/{id}`](https://docs.rephut.com/developers/reference/shipments#get-a-shipment) and confirm it with [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote), sending the `version` you read. If the shipment changed in between you get `409 shipment_changed`: read it again and confirm the new version.
5. Confirming creates an amount due (`dueCents`); pay it in the portal. We then ship it and add the tracking numbers (webhooks `shipment.status_changed` and `shipment.tracking_updated`).

We also prepare shipments for you; they appear here once we send them to you for confirmation. To send us feedback on a quote instead of confirming it, use the portal.

## Shipment statuses

| Value | Meaning |
|---|---|
| `DRAFT` | Preparing: we are packing it and haven't sent the freight quote yet. A shipment you asked for can still be cancelled. |
| `PENDING_CONFIRMATION` | Awaiting your confirmation of the freight quote. Confirm it with POST /v1/shipments/{id}/confirm. |
| `AWAITING_PAYMENT` | Confirmed; waiting for your payment. Pay shipments in the portal. |
| `PAID` | Paid; waiting to ship. |
| `SHIPPED` | Shipped. `trackingNos` lists the tracking numbers. |
| `CANCELLED` | Cancelled. |

## Shipment kinds

| Value | Meaning |
|---|---|
| `WHOLESALE` | Ships to an address you give. |
| `FBA` | Ships to an Amazon FBA warehouse. |

## Transport modes

| Value | Meaning |
|---|---|
| `AIR` | Air freight. |
| `SEA` | Sea freight. |
| `EXPRESS` | Express. |
| `TRUCK` | Truck. |

## List shipments

`GET /v1/shipments`

Shipments we have sent you for confirmation, and the ones you asked for from your stock. Newest first.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/shipments` |
| Permission | `shipments:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `id` | string | Shipment id. |
| `number` | string | Our shipment number. |
| `kind` | string | Where it goes. See [Shipment kinds](#shipment-kinds). One of `WHOLESALE`, `FBA`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Shipment status. See [Shipment statuses](#shipment-statuses). One of `DRAFT`, `PENDING_CONFIRMATION`, `AWAITING_PAYMENT`, `PAID`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `boxCount` | integer | Number of boxes packed. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `receivableCents` | integer | Total to pay for the shipment, in US cents. |
| `paidCents` | integer | Paid so far minus refunds, in US cents. |
| `createdAt` | string (date-time) | When the shipment was created. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/shipments?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/shipments?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/shipments?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "id": "cm3s5hp0m0001ent2w3e4r5t",
      "number": "S2611090002",
      "kind": "WHOLESALE",
      "kindLabel": "Wholesale",
      "status": "PENDING_CONFIRMATION",
      "statusLabel": "Awaiting your confirmation",
      "boxCount": 2,
      "currency": "USD",
      "receivableCents": 19320,
      "paidCents": 0,
      "createdAt": "2026-11-09T04:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

## Get a shipment

`GET /v1/shipments/{id}`

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/shipments/{id}` |
| Permission | `shipments:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Shipment id, from [`GET /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#list-shipments) or the response of [`POST /v1/shipments`](https://docs.rephut.com/developers/reference/shipments#request-a-shipment-from-your-stock). An id that doesn't exist, isn't yours or isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Shipment id. |
| `number` | string | Our shipment number. |
| `kind` | string | Where it goes. See [Shipment kinds](#shipment-kinds). One of `WHOLESALE`, `FBA`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Shipment status. See [Shipment statuses](#shipment-statuses). One of `DRAFT`, `PENDING_CONFIRMATION`, `AWAITING_PAYMENT`, `PAID`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `createdAt` | string (date-time) | When the shipment was created. |
| `submittedAt` | string (date-time) or null | When we sent you the freight quote; null before that. |
| `requestedByCustomer` | boolean | `true` when you asked for the shipment (in the portal or the API); `false` when we prepared it for you. |
| `lines` | array of objects | Products in the shipment. |
| `lines[].sku` | string | Our SKU. |
| `lines[].name` | string | Product name in English. |
| `lines[].qty` | integer | Quantity. |
| `transportLabel` | string | How it travels, in English, for example Air freight. |
| `shippingOption` | string or null | Name of the shipping option; "Assigned by our team" when the channel has no public name; null until a channel is set. |
| `address` | object | Where it ships to. |
| `address.recipientName` | string | Recipient name. |
| `address.recipientPhone` | string | Recipient phone number. |
| `address.address1` | string | Address line 1. |
| `address.address2` | string | Address line 2. |
| `address.city` | string | City. |
| `address.province` | string | State or province. |
| `address.postalCode` | string | Postal code. |
| `address.countryCode` | string or null | Two-letter country code; null when not set. |
| `fbaWarehouseCode` | string | Amazon warehouse code for FBA shipments; empty otherwise. |
| `fbaShipmentId` | string | Your Amazon FBA shipment id; empty when not given. |
| `boxes` | array of objects | Packed boxes. |
| `boxes[].boxNo` | integer | Box number. |
| `boxes[].weightG` | integer | Box weight in grams. |
| `boxes[].lengthCm` | number | Length in centimetres. |
| `boxes[].widthCm` | number | Width in centimetres. |
| `boxes[].heightCm` | number | Height in centimetres. |
| `boxes[].lines` | array of objects | Products in this box. |
| `boxes[].lines[].sku` | string | Our SKU. |
| `boxes[].lines[].name` | string | Product name in English. |
| `boxes[].lines[].qty` | integer | Quantity. |
| `boxCount` | integer | Number of boxes packed. |
| `totalWeightG` | integer | Weight of all boxes in grams. |
| `chargeableG` | integer or null | Weight we charge for, in grams. Only set when the shipment is priced automatically from our channel rates (not when freight was entered by hand), and null until that price is worked out. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `freightCents` | integer or null | Freight in US cents; null until quoted. |
| `fees` | array of objects | Other fees on the shipment. |
| `fees[].label` | string | Fee name. |
| `fees[].description` | string | What the fee is for. |
| `fees[].amountCents` | integer | Amount in US cents. |
| `receivableCents` | integer | Total to pay for the shipment, in US cents. |
| `paidCents` | integer | Paid so far minus refunds, in US cents. |
| `dueCents` | integer | Still to pay, in US cents; 0 when the shipment is cancelled. |
| `paymentInstructions` | array of objects | How to pay; empty when nothing is due. |
| `paymentInstructions[].name` | string | Payment method name. |
| `paymentInstructions[].instructions` | string | How to pay with this method. |
| `trackingNos` | array of strings | Tracking numbers; empty until shipped. Webhook `shipment.tracking_updated` tells you when they are added. |
| `shippedAt` | string (date-time) or null | When it shipped; null until then. |
| `confirmedAt` | string (date-time) or null | When the shipment was confirmed (by you or by our team for you); null before that. |
| `canConfirm` | boolean | `true` when you can confirm it now with [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote). |
| `canCancel` | boolean | `true` when you can cancel it now with [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested): a shipment you asked for that we haven't quoted yet. |
| `version` | string | Send this back when you confirm the shipment. |
| `feedback` | string | Feedback about the quote you sent us from the portal; empty when none. |
| `feedbackAt` | string (date-time) or null | When you sent the feedback; null when none. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3s5hp0m0001ent2w3e4r5t",
    "number": "S2611090002",
    "kind": "WHOLESALE",
    "kindLabel": "Wholesale",
    "status": "PENDING_CONFIRMATION",
    "statusLabel": "Awaiting your confirmation",
    "createdAt": "2026-11-09T04:00:00.000Z",
    "submittedAt": "2026-11-10T08:00:00.000Z",
    "requestedByCustomer": true,
    "lines": [
      {
        "sku": "FB-10231-BLK-M",
        "name": "Cotton crew neck T-shirt",
        "qty": 100
      }
    ],
    "transportLabel": "Air freight",
    "shippingOption": "US Air Freight",
    "address": {
      "recipientName": "Alex Morgan",
      "recipientPhone": "+1 555 0100",
      "address1": "40 Example Avenue",
      "address2": "Unit 2",
      "city": "Springfield",
      "province": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "fbaWarehouseCode": "",
    "fbaShipmentId": "",
    "boxes": [
      {
        "boxNo": 1,
        "weightG": 10400,
        "lengthCm": 50,
        "widthCm": 40,
        "heightCm": 35,
        "lines": [
          {
            "sku": "FB-10231-BLK-M",
            "name": "Cotton crew neck T-shirt",
            "qty": 50
          }
        ]
      },
      {
        "boxNo": 2,
        "weightG": 10400,
        "lengthCm": 50,
        "widthCm": 40,
        "heightCm": 35,
        "lines": [
          {
            "sku": "FB-10231-BLK-M",
            "name": "Cotton crew neck T-shirt",
            "qty": 50
          }
        ]
      }
    ],
    "boxCount": 2,
    "totalWeightG": 20800,
    "chargeableG": 23400,
    "currency": "USD",
    "freightCents": 18720,
    "fees": [
      {
        "label": "Labeling",
        "description": "Carton labels",
        "amountCents": 600
      }
    ],
    "receivableCents": 19320,
    "paidCents": 0,
    "dueCents": 19320,
    "paymentInstructions": [
      {
        "name": "Bank transfer",
        "instructions": "Pay to the account shown in the portal under Wallet → Top up, quoting S2611090002."
      }
    ],
    "trackingNos": [],
    "shippedAt": null,
    "confirmedAt": null,
    "canConfirm": true,
    "canCancel": false,
    "version": "2026-11-10T08:00:00.000Z",
    "feedback": "",
    "feedbackAt": null
  }
}
```

## Estimate shipping for a shipment from your stock

`POST /v1/shipments/estimate`

Lists the shipping options for these products and destination, cheapest first, with prices estimated from the total product weight. Nothing is saved, and it works while your account is on hold.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/shipments/estimate` |
| Permission | `shipments:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | Yes | `application/json` |

### Request body

A JSON object. Fields not listed here are ignored.

| Field | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | Yes | Two-letter country code, for example US. |
| `postalCode` | string | No | Postal code. Some countries are priced by postal code zone; without it you get a price range. Up to 200 characters. Default: `""`. |
| `lines` | array of objects | Yes | Products from your stock (productId from GET /v1/inventory) with quantities. 1 to 200 items. |
| `lines[].productId` | string | Yes | Our product id from [`GET /v1/inventory`](https://docs.rephut.com/developers/reference/inventory#list-your-stock). Not empty. |
| `lines[].qty` | integer | Yes | Quantity. From 1 to 100,000. |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `available` | boolean | false when we can't price shipments right now; options is then empty. You can still create the shipment and let us choose. |
| `totalWeightG` | integer | Total weight of the products in your stock; products that aren't in your stock count as 0. |
| `currency` | string | Currency of every price. Always `USD`. |
| `options` | array of objects | Shipping options for the shipment, cheapest first. Empty when none fits the weight or destination. The price is a guide: we price the shipment again from the packed boxes. |
| `options[].channelId` | string | Send this as channelId to use this shipping option. |
| `options[].name` | string | Name of the shipping option in English. |
| `options[].priceCents` | integer | Estimated shipping in US cents. |
| `options[].priceMaxCents` | integer or null | Upper end of the estimate when the price depends on the postal code; null otherwise. |
| `options[].transitLabel` | string | Delivery time in English, for example 7–12 days. |
| `options[].chargeableG` | integer | Weight the price is based on, in grams. |
| `options[].cheapest` | boolean | `true` for the cheapest option. |
| `options[].fastest` | boolean | `true` for the fastest option. |
| `options[].transportMode` | string | How it travels. See [Transport modes](#transport-modes). One of `AIR`, `SEA`, `EXPRESS`, `TRUCK`. |
| `options[].transportLabel` | string | English text for display. It may change; rely on the code next to it. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/shipments/estimate' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "countryCode": "US",
  "postalCode": "62701",
  "lines": [
    {
      "productId": "cm3p4r0d0001xyz7k2m9q8w1",
      "qty": 100
    }
  ]
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/shipments/estimate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "countryCode": "US",
    "postalCode": "62701",
    "lines": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "qty": 100
      }
    ]
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/shipments/estimate",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    json={
        "countryCode": "US",
        "postalCode": "62701",
        "lines": [
            {
                "productId": "cm3p4r0d0001xyz7k2m9q8w1",
                "qty": 100,
            },
        ],
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "available": true,
    "totalWeightG": 20000,
    "currency": "USD",
    "options": [
      {
        "channelId": "cm1ch0004ussea0000000004",
        "name": "US Sea Freight",
        "priceCents": 9800,
        "priceMaxCents": null,
        "transitLabel": "30–40 days",
        "chargeableG": 20000,
        "cheapest": true,
        "fastest": false,
        "transportMode": "SEA",
        "transportLabel": "Sea freight"
      },
      {
        "channelId": "cm1ch0003usair0000000003",
        "name": "US Air Freight",
        "priceCents": 18000,
        "priceMaxCents": null,
        "transitLabel": "10–15 days",
        "chargeableG": 22500,
        "cheapest": false,
        "fastest": true,
        "transportMode": "AIR",
        "transportLabel": "Air freight"
      }
    ]
  }
}
```

## Request a shipment from your stock

`POST /v1/shipments`

Creates a shipment like the portal's New shipment form and reserves the stock; not enough available stock returns 422 stock_short. We pack it, set the shipping and send you the freight quote; then confirm it with POST /v1/shipments/{id}/confirm. You can cancel it until we send the quote. Creating it doesn't charge your wallet. Send an Idempotency-Key so a retry can't create it twice.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/shipments` |
| Permission | `shipments:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Required |
| Success | 201 Created |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | Yes | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

A JSON object. Fields not listed here are ignored.

| Field | Type | Required | Description |
|---|---|---|---|
| `kind` | string | Yes | WHOLESALE ships to an address, FBA to an Amazon warehouse. One of `WHOLESALE`, `FBA`. |
| `channelId` | string | No | A shipping option from POST /v1/shipments/estimate (options[].channelId). Leave empty to let us choose; then send transportMode. Up to 64 characters. Default: `""`. |
| `transportMode` | string | No | How we should ship it when channelId is empty: AIR, SEA, EXPRESS, TRUCK. Default: `""`. |
| `recipientName` | string | No | Recipient name. Required for WHOLESALE. Up to 200 characters. Default: `""`. |
| `recipientPhone` | string | No | Recipient phone number. Up to 200 characters. Default: `""`. |
| `address1` | string | No | Address line 1. Required for WHOLESALE. Up to 200 characters. Default: `""`. |
| `address2` | string | No | Address line 2. Up to 200 characters. Default: `""`. |
| `city` | string | No | City. Required for WHOLESALE. Up to 200 characters. Default: `""`. |
| `province` | string | No | State or province. Up to 200 characters. Default: `""`. |
| `postalCode` | string | No | Postal code. Up to 200 characters. Default: `""`. |
| `countryCode` | string | Yes | Two-letter country code, for example US. |
| `fbaWarehouseCode` | string | No | Amazon warehouse code; required for FBA. Up to 50 characters. Default: `""`. |
| `fbaShipmentId` | string | No | Your Amazon FBA shipment id, for FBA shipments; optional. Up to 100 characters. Default: `""`. |
| `note` | string | No | Note for our warehouse team. Up to 2,000 characters. Default: `""`. |
| `lines` | array of objects | Yes | Products from your stock (productId from GET /v1/inventory) with quantities; each product once. 1 to 200 items. |
| `lines[].productId` | string | Yes | Our product id from [`GET /v1/inventory`](https://docs.rephut.com/developers/reference/inventory#list-your-stock). Not empty. |
| `lines[].qty` | integer | Yes | Quantity to ship from your available stock. From 1 to 100,000. |

### Response

`201` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Shipment id. |
| `number` | string | Our shipment number. |
| `kind` | string | Where it goes. See [Shipment kinds](#shipment-kinds). One of `WHOLESALE`, `FBA`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Shipment status. See [Shipment statuses](#shipment-statuses). One of `DRAFT`, `PENDING_CONFIRMATION`, `AWAITING_PAYMENT`, `PAID`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `createdAt` | string (date-time) | When the shipment was created. |
| `submittedAt` | string (date-time) or null | When we sent you the freight quote; null before that. |
| `requestedByCustomer` | boolean | `true` when you asked for the shipment (in the portal or the API); `false` when we prepared it for you. |
| `lines` | array of objects | Products in the shipment. |
| `lines[].sku` | string | Our SKU. |
| `lines[].name` | string | Product name in English. |
| `lines[].qty` | integer | Quantity. |
| `transportLabel` | string | How it travels, in English, for example Air freight. |
| `shippingOption` | string or null | Name of the shipping option; "Assigned by our team" when the channel has no public name; null until a channel is set. |
| `address` | object | Where it ships to. |
| `address.recipientName` | string | Recipient name. |
| `address.recipientPhone` | string | Recipient phone number. |
| `address.address1` | string | Address line 1. |
| `address.address2` | string | Address line 2. |
| `address.city` | string | City. |
| `address.province` | string | State or province. |
| `address.postalCode` | string | Postal code. |
| `address.countryCode` | string or null | Two-letter country code; null when not set. |
| `fbaWarehouseCode` | string | Amazon warehouse code for FBA shipments; empty otherwise. |
| `fbaShipmentId` | string | Your Amazon FBA shipment id; empty when not given. |
| `boxes` | array of objects | Packed boxes. |
| `boxes[].boxNo` | integer | Box number. |
| `boxes[].weightG` | integer | Box weight in grams. |
| `boxes[].lengthCm` | number | Length in centimetres. |
| `boxes[].widthCm` | number | Width in centimetres. |
| `boxes[].heightCm` | number | Height in centimetres. |
| `boxes[].lines` | array of objects | Products in this box. |
| `boxes[].lines[].sku` | string | Our SKU. |
| `boxes[].lines[].name` | string | Product name in English. |
| `boxes[].lines[].qty` | integer | Quantity. |
| `boxCount` | integer | Number of boxes packed. |
| `totalWeightG` | integer | Weight of all boxes in grams. |
| `chargeableG` | integer or null | Weight we charge for, in grams. Only set when the shipment is priced automatically from our channel rates (not when freight was entered by hand), and null until that price is worked out. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `freightCents` | integer or null | Freight in US cents; null until quoted. |
| `fees` | array of objects | Other fees on the shipment. |
| `fees[].label` | string | Fee name. |
| `fees[].description` | string | What the fee is for. |
| `fees[].amountCents` | integer | Amount in US cents. |
| `receivableCents` | integer | Total to pay for the shipment, in US cents. |
| `paidCents` | integer | Paid so far minus refunds, in US cents. |
| `dueCents` | integer | Still to pay, in US cents; 0 when the shipment is cancelled. |
| `paymentInstructions` | array of objects | How to pay; empty when nothing is due. |
| `paymentInstructions[].name` | string | Payment method name. |
| `paymentInstructions[].instructions` | string | How to pay with this method. |
| `trackingNos` | array of strings | Tracking numbers; empty until shipped. Webhook `shipment.tracking_updated` tells you when they are added. |
| `shippedAt` | string (date-time) or null | When it shipped; null until then. |
| `confirmedAt` | string (date-time) or null | When the shipment was confirmed (by you or by our team for you); null before that. |
| `canConfirm` | boolean | `true` when you can confirm it now with [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote). |
| `canCancel` | boolean | `true` when you can cancel it now with [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested): a shipment you asked for that we haven't quoted yet. |
| `version` | string | Send this back when you confirm the shipment. |
| `feedback` | string | Feedback about the quote you sent us from the portal; empty when none. |
| `feedbackAt` | string (date-time) or null | When you sent the feedback; null when none. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `idempotency_key_required` | 400 | This request needs an Idempotency-Key header. |
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `preference_channel_unavailable` | 422 | This shipping option is no longer available. Please choose another one. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `shipments_unavailable` | 422 | We can't take shipments right now. Please contact your account manager. |
| `stock_short` | 422 | Some products don't have enough available stock. Refresh the page to see the latest quantities and try again. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/shipments' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: c41d9a7e-2f58-4b0c-a6e3-91d7f05b2c84' \
  -d '{
  "kind": "WHOLESALE",
  "channelId": "cm1ch0003usair0000000003",
  "transportMode": "",
  "recipientName": "Alex Morgan",
  "recipientPhone": "+1 555 0100",
  "address1": "40 Example Avenue",
  "address2": "Unit 2",
  "city": "Springfield",
  "province": "IL",
  "postalCode": "62701",
  "countryCode": "US",
  "fbaWarehouseCode": "",
  "fbaShipmentId": "",
  "note": "Two cartons, please.",
  "lines": [
    {
      "productId": "cm3p4r0d0001xyz7k2m9q8w1",
      "qty": 100
    }
  ]
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/shipments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "c41d9a7e-2f58-4b0c-a6e3-91d7f05b2c84",
  },
  body: JSON.stringify({
    "kind": "WHOLESALE",
    "channelId": "cm1ch0003usair0000000003",
    "transportMode": "",
    "recipientName": "Alex Morgan",
    "recipientPhone": "+1 555 0100",
    "address1": "40 Example Avenue",
    "address2": "Unit 2",
    "city": "Springfield",
    "province": "IL",
    "postalCode": "62701",
    "countryCode": "US",
    "fbaWarehouseCode": "",
    "fbaShipmentId": "",
    "note": "Two cartons, please.",
    "lines": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "qty": 100
      }
    ]
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/shipments",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "c41d9a7e-2f58-4b0c-a6e3-91d7f05b2c84",
    },
    json={
        "kind": "WHOLESALE",
        "channelId": "cm1ch0003usair0000000003",
        "transportMode": "",
        "recipientName": "Alex Morgan",
        "recipientPhone": "+1 555 0100",
        "address1": "40 Example Avenue",
        "address2": "Unit 2",
        "city": "Springfield",
        "province": "IL",
        "postalCode": "62701",
        "countryCode": "US",
        "fbaWarehouseCode": "",
        "fbaShipmentId": "",
        "note": "Two cartons, please.",
        "lines": [
            {
                "productId": "cm3p4r0d0001xyz7k2m9q8w1",
                "qty": 100,
            },
        ],
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=201
{
  "success": true,
  "data": {
    "id": "cm3s5hp0m0001ent2w3e4r5t",
    "number": "S2611090002",
    "kind": "WHOLESALE",
    "kindLabel": "Wholesale",
    "status": "DRAFT",
    "statusLabel": "Preparing",
    "createdAt": "2026-11-09T04:00:00.000Z",
    "submittedAt": null,
    "requestedByCustomer": true,
    "lines": [
      {
        "sku": "FB-10231-BLK-M",
        "name": "Cotton crew neck T-shirt",
        "qty": 100
      }
    ],
    "transportLabel": "Air freight",
    "shippingOption": "US Air Freight",
    "address": {
      "recipientName": "Alex Morgan",
      "recipientPhone": "+1 555 0100",
      "address1": "40 Example Avenue",
      "address2": "Unit 2",
      "city": "Springfield",
      "province": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "fbaWarehouseCode": "",
    "fbaShipmentId": "",
    "boxes": [],
    "boxCount": 0,
    "totalWeightG": 0,
    "chargeableG": null,
    "currency": "USD",
    "freightCents": null,
    "fees": [],
    "receivableCents": 0,
    "paidCents": 0,
    "dueCents": 0,
    "paymentInstructions": [],
    "trackingNos": [],
    "shippedAt": null,
    "confirmedAt": null,
    "canConfirm": false,
    "canCancel": true,
    "version": "2026-11-09T04:00:00.000Z",
    "feedback": "",
    "feedbackAt": null
  }
}
```

## Cancel a shipment you requested

`POST /v1/shipments/{id}/cancel`

Only shipments you requested that we haven't quoted yet (status DRAFT) can be cancelled; their stock is available again. Otherwise 409 shipment_not_cancellable: contact your account manager. No request body.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/shipments/{id}/cancel` |
| Permission | `shipments:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Optional, recommended |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Shipment id. An id that doesn't exist or isn't yours returns 404 `shipment_not_found`; an id that isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Idempotency-Key` | No | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

No request body.

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Shipment id. |
| `number` | string | Our shipment number. |
| `kind` | string | Where it goes. See [Shipment kinds](#shipment-kinds). One of `WHOLESALE`, `FBA`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Shipment status. See [Shipment statuses](#shipment-statuses). One of `DRAFT`, `PENDING_CONFIRMATION`, `AWAITING_PAYMENT`, `PAID`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `createdAt` | string (date-time) | When the shipment was created. |
| `submittedAt` | string (date-time) or null | When we sent you the freight quote; null before that. |
| `requestedByCustomer` | boolean | `true` when you asked for the shipment (in the portal or the API); `false` when we prepared it for you. |
| `lines` | array of objects | Products in the shipment. |
| `lines[].sku` | string | Our SKU. |
| `lines[].name` | string | Product name in English. |
| `lines[].qty` | integer | Quantity. |
| `transportLabel` | string | How it travels, in English, for example Air freight. |
| `shippingOption` | string or null | Name of the shipping option; "Assigned by our team" when the channel has no public name; null until a channel is set. |
| `address` | object | Where it ships to. |
| `address.recipientName` | string | Recipient name. |
| `address.recipientPhone` | string | Recipient phone number. |
| `address.address1` | string | Address line 1. |
| `address.address2` | string | Address line 2. |
| `address.city` | string | City. |
| `address.province` | string | State or province. |
| `address.postalCode` | string | Postal code. |
| `address.countryCode` | string or null | Two-letter country code; null when not set. |
| `fbaWarehouseCode` | string | Amazon warehouse code for FBA shipments; empty otherwise. |
| `fbaShipmentId` | string | Your Amazon FBA shipment id; empty when not given. |
| `boxes` | array of objects | Packed boxes. |
| `boxes[].boxNo` | integer | Box number. |
| `boxes[].weightG` | integer | Box weight in grams. |
| `boxes[].lengthCm` | number | Length in centimetres. |
| `boxes[].widthCm` | number | Width in centimetres. |
| `boxes[].heightCm` | number | Height in centimetres. |
| `boxes[].lines` | array of objects | Products in this box. |
| `boxes[].lines[].sku` | string | Our SKU. |
| `boxes[].lines[].name` | string | Product name in English. |
| `boxes[].lines[].qty` | integer | Quantity. |
| `boxCount` | integer | Number of boxes packed. |
| `totalWeightG` | integer | Weight of all boxes in grams. |
| `chargeableG` | integer or null | Weight we charge for, in grams. Only set when the shipment is priced automatically from our channel rates (not when freight was entered by hand), and null until that price is worked out. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `freightCents` | integer or null | Freight in US cents; null until quoted. |
| `fees` | array of objects | Other fees on the shipment. |
| `fees[].label` | string | Fee name. |
| `fees[].description` | string | What the fee is for. |
| `fees[].amountCents` | integer | Amount in US cents. |
| `receivableCents` | integer | Total to pay for the shipment, in US cents. |
| `paidCents` | integer | Paid so far minus refunds, in US cents. |
| `dueCents` | integer | Still to pay, in US cents; 0 when the shipment is cancelled. |
| `paymentInstructions` | array of objects | How to pay; empty when nothing is due. |
| `paymentInstructions[].name` | string | Payment method name. |
| `paymentInstructions[].instructions` | string | How to pay with this method. |
| `trackingNos` | array of strings | Tracking numbers; empty until shipped. Webhook `shipment.tracking_updated` tells you when they are added. |
| `shippedAt` | string (date-time) or null | When it shipped; null until then. |
| `confirmedAt` | string (date-time) or null | When the shipment was confirmed (by you or by our team for you); null before that. |
| `canConfirm` | boolean | `true` when you can confirm it now with [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote). |
| `canCancel` | boolean | `true` when you can cancel it now with [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested): a shipment you asked for that we haven't quoted yet. |
| `version` | string | Send this back when you confirm the shipment. |
| `feedback` | string | Feedback about the quote you sent us from the portal; empty when none. |
| `feedbackAt` | string (date-time) or null | When you sent the feedback; null when none. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `shipment_not_found` | 404 | This shipment could not be found. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `shipment_not_cancellable` | 409 | This shipment can no longer be cancelled here because we've already sent you the freight quote. Please contact your account manager. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t/cancel' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H 'Idempotency-Key: 2e6a9f04-b7d1-4c38-a5e2-60f8c1d94b73'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Idempotency-Key": "2e6a9f04-b7d1-4c38-a5e2-60f8c1d94b73",
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "2e6a9f04-b7d1-4c38-a5e2-60f8c1d94b73",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3s5hp0m0001ent2w3e4r5t",
    "number": "S2611090002",
    "kind": "WHOLESALE",
    "kindLabel": "Wholesale",
    "status": "CANCELLED",
    "statusLabel": "Cancelled",
    "createdAt": "2026-11-09T04:00:00.000Z",
    "submittedAt": null,
    "requestedByCustomer": true,
    "lines": [
      {
        "sku": "FB-10231-BLK-M",
        "name": "Cotton crew neck T-shirt",
        "qty": 100
      }
    ],
    "transportLabel": "Air freight",
    "shippingOption": "US Air Freight",
    "address": {
      "recipientName": "Alex Morgan",
      "recipientPhone": "+1 555 0100",
      "address1": "40 Example Avenue",
      "address2": "Unit 2",
      "city": "Springfield",
      "province": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "fbaWarehouseCode": "",
    "fbaShipmentId": "",
    "boxes": [],
    "boxCount": 0,
    "totalWeightG": 0,
    "chargeableG": null,
    "currency": "USD",
    "freightCents": null,
    "fees": [],
    "receivableCents": 0,
    "paidCents": 0,
    "dueCents": 0,
    "paymentInstructions": [],
    "trackingNos": [],
    "shippedAt": null,
    "confirmedAt": null,
    "canConfirm": false,
    "canCancel": false,
    "version": "2026-11-09T05:00:00.000Z",
    "feedback": "",
    "feedbackAt": null
  }
}
```

## Confirm a shipment's freight quote

`POST /v1/shipments/{id}/confirm`

Confirms the shipment as you saw it, like the Confirm button in the portal. Only shipments with status PENDING_CONFIRMATION can be confirmed (otherwise 409 shipment_not_decidable). Confirming a shipment doesn't charge your wallet. It creates an amount due that you pay separately.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/shipments/{id}/confirm` |
| Permission | `shipments:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Optional, recommended |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Shipment id. An id that doesn't exist or isn't yours returns 404 `shipment_not_found`; an id that isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

A JSON object. Fields not listed here are ignored.

| Field | Type | Required | Description |
|---|---|---|---|
| `version` | string | Yes | The shipment's version from GET /v1/shipments/{id}. If the shipment changed since, you get 409 shipment_changed: read it again and confirm the new version. Not empty. |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Shipment id. |
| `number` | string | Our shipment number. |
| `kind` | string | Where it goes. See [Shipment kinds](#shipment-kinds). One of `WHOLESALE`, `FBA`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Shipment status. See [Shipment statuses](#shipment-statuses). One of `DRAFT`, `PENDING_CONFIRMATION`, `AWAITING_PAYMENT`, `PAID`, `SHIPPED`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `createdAt` | string (date-time) | When the shipment was created. |
| `submittedAt` | string (date-time) or null | When we sent you the freight quote; null before that. |
| `requestedByCustomer` | boolean | `true` when you asked for the shipment (in the portal or the API); `false` when we prepared it for you. |
| `lines` | array of objects | Products in the shipment. |
| `lines[].sku` | string | Our SKU. |
| `lines[].name` | string | Product name in English. |
| `lines[].qty` | integer | Quantity. |
| `transportLabel` | string | How it travels, in English, for example Air freight. |
| `shippingOption` | string or null | Name of the shipping option; "Assigned by our team" when the channel has no public name; null until a channel is set. |
| `address` | object | Where it ships to. |
| `address.recipientName` | string | Recipient name. |
| `address.recipientPhone` | string | Recipient phone number. |
| `address.address1` | string | Address line 1. |
| `address.address2` | string | Address line 2. |
| `address.city` | string | City. |
| `address.province` | string | State or province. |
| `address.postalCode` | string | Postal code. |
| `address.countryCode` | string or null | Two-letter country code; null when not set. |
| `fbaWarehouseCode` | string | Amazon warehouse code for FBA shipments; empty otherwise. |
| `fbaShipmentId` | string | Your Amazon FBA shipment id; empty when not given. |
| `boxes` | array of objects | Packed boxes. |
| `boxes[].boxNo` | integer | Box number. |
| `boxes[].weightG` | integer | Box weight in grams. |
| `boxes[].lengthCm` | number | Length in centimetres. |
| `boxes[].widthCm` | number | Width in centimetres. |
| `boxes[].heightCm` | number | Height in centimetres. |
| `boxes[].lines` | array of objects | Products in this box. |
| `boxes[].lines[].sku` | string | Our SKU. |
| `boxes[].lines[].name` | string | Product name in English. |
| `boxes[].lines[].qty` | integer | Quantity. |
| `boxCount` | integer | Number of boxes packed. |
| `totalWeightG` | integer | Weight of all boxes in grams. |
| `chargeableG` | integer or null | Weight we charge for, in grams. Only set when the shipment is priced automatically from our channel rates (not when freight was entered by hand), and null until that price is worked out. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `freightCents` | integer or null | Freight in US cents; null until quoted. |
| `fees` | array of objects | Other fees on the shipment. |
| `fees[].label` | string | Fee name. |
| `fees[].description` | string | What the fee is for. |
| `fees[].amountCents` | integer | Amount in US cents. |
| `receivableCents` | integer | Total to pay for the shipment, in US cents. |
| `paidCents` | integer | Paid so far minus refunds, in US cents. |
| `dueCents` | integer | Still to pay, in US cents; 0 when the shipment is cancelled. |
| `paymentInstructions` | array of objects | How to pay; empty when nothing is due. |
| `paymentInstructions[].name` | string | Payment method name. |
| `paymentInstructions[].instructions` | string | How to pay with this method. |
| `trackingNos` | array of strings | Tracking numbers; empty until shipped. Webhook `shipment.tracking_updated` tells you when they are added. |
| `shippedAt` | string (date-time) or null | When it shipped; null until then. |
| `confirmedAt` | string (date-time) or null | When the shipment was confirmed (by you or by our team for you); null before that. |
| `canConfirm` | boolean | `true` when you can confirm it now with [`POST /v1/shipments/{id}/confirm`](https://docs.rephut.com/developers/reference/shipments#confirm-a-shipment-s-freight-quote). |
| `canCancel` | boolean | `true` when you can cancel it now with [`POST /v1/shipments/{id}/cancel`](https://docs.rephut.com/developers/reference/shipments#cancel-a-shipment-you-requested): a shipment you asked for that we haven't quoted yet. |
| `version` | string | Send this back when you confirm the shipment. |
| `feedback` | string | Feedback about the quote you sent us from the portal; empty when none. |
| `feedbackAt` | string (date-time) or null | When you sent the feedback; null when none. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `shipment_not_found` | 404 | This shipment could not be found. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `shipment_changed` | 409 | This shipment was updated. Please review it again. |
| `shipment_not_decidable` | 409 | This shipment can no longer be confirmed or commented on. It may have been updated or already confirmed. Please refresh the page. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t/confirm' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: 9a1c5e3d-4f72-4b86-8d09-e7b2a6c0f135' \
  -d '{
  "version": "2026-11-10T08:00:00.000Z"
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t/confirm", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "9a1c5e3d-4f72-4b86-8d09-e7b2a6c0f135",
  },
  body: JSON.stringify({
    "version": "2026-11-10T08:00:00.000Z"
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/shipments/cm3s5hp0m0001ent2w3e4r5t/confirm",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "9a1c5e3d-4f72-4b86-8d09-e7b2a6c0f135",
    },
    json={
        "version": "2026-11-10T08:00:00.000Z",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3s5hp0m0001ent2w3e4r5t",
    "number": "S2611090002",
    "kind": "WHOLESALE",
    "kindLabel": "Wholesale",
    "status": "AWAITING_PAYMENT",
    "statusLabel": "Awaiting payment",
    "createdAt": "2026-11-09T04:00:00.000Z",
    "submittedAt": "2026-11-10T08:00:00.000Z",
    "requestedByCustomer": true,
    "lines": [
      {
        "sku": "FB-10231-BLK-M",
        "name": "Cotton crew neck T-shirt",
        "qty": 100
      }
    ],
    "transportLabel": "Air freight",
    "shippingOption": "US Air Freight",
    "address": {
      "recipientName": "Alex Morgan",
      "recipientPhone": "+1 555 0100",
      "address1": "40 Example Avenue",
      "address2": "Unit 2",
      "city": "Springfield",
      "province": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "fbaWarehouseCode": "",
    "fbaShipmentId": "",
    "boxes": [
      {
        "boxNo": 1,
        "weightG": 10400,
        "lengthCm": 50,
        "widthCm": 40,
        "heightCm": 35,
        "lines": [
          {
            "sku": "FB-10231-BLK-M",
            "name": "Cotton crew neck T-shirt",
            "qty": 50
          }
        ]
      },
      {
        "boxNo": 2,
        "weightG": 10400,
        "lengthCm": 50,
        "widthCm": 40,
        "heightCm": 35,
        "lines": [
          {
            "sku": "FB-10231-BLK-M",
            "name": "Cotton crew neck T-shirt",
            "qty": 50
          }
        ]
      }
    ],
    "boxCount": 2,
    "totalWeightG": 20800,
    "chargeableG": 23400,
    "currency": "USD",
    "freightCents": 18720,
    "fees": [
      {
        "label": "Labeling",
        "description": "Carton labels",
        "amountCents": 600
      }
    ],
    "receivableCents": 19320,
    "paidCents": 0,
    "dueCents": 19320,
    "paymentInstructions": [
      {
        "name": "Bank transfer",
        "instructions": "Pay to the account shown in the portal under Wallet → Top up, quoting S2611090002."
      }
    ],
    "trackingNos": [],
    "shippedAt": null,
    "confirmedAt": "2026-11-10T09:30:00.000Z",
    "canConfirm": false,
    "canCancel": false,
    "version": "2026-11-10T09:30:00.000Z",
    "feedback": "",
    "feedbackAt": null
  }
}
```

---

Source: https://docs.rephut.com/developers/reference/requests

# Sourcing and reorder requests

- A **sourcing request** asks us to find products. Give a link for each product (the API can't upload images), the quantity and, if you like, a target price. We reply with a quote: see [Quotes](https://docs.rephut.com/developers/reference/quotes).
- A **reorder request** asks us to restock products at your agreed prices. Only products with `canReorder: true` in [`GET /v1/products`](https://docs.rephut.com/developers/reference/products#list-your-products) can be reordered (`422 product_not_reorderable` otherwise). We turn it into a purchase order.

A request can have up to 20 products. Withdraw requests in the portal; the API can't withdraw them yet. The list is sorted newest first. There is no `updatedSince` here: use webhooks and GET, or read the first pages again to find new ones (the list is newest first). See [Incremental sync](https://docs.rephut.com/developers/incremental-sync).

## Request kinds

| Value | Meaning |
|---|---|
| `SOURCING` | Ask us to find and quote new products. |
| `REORDER` | Restock products at your agreed prices. |

## Request statuses

| Value | Meaning |
|---|---|
| `SUBMITTED` | We received the request. |
| `IN_PROGRESS` | We are working on it. |
| `QUOTED` | We sent a quote; `quoteId` points to it. |
| `DONE` | Completed, for example a purchase order was created (`purchaseOrderId`). |
| `CANCELLED` | Cancelled by you or by us; `cancelledByCustomer` and `cancelReason` say which and why. |

## Purposes

| Value | Meaning |
|---|---|
| `DROPSHIP_STOCK` | Stock kept in our warehouse for your dropship orders. |
| `SHIP_TO_ME` | Goods we ship to you. |
| `AMAZON_FBA` | Goods for Amazon FBA. |

## List sourcing and reorder requests

`GET /v1/requests`

Newest first.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/requests` |
| Permission | `requests:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `id` | string | Request id. |
| `number` | string | Our request number. |
| `kind` | string | Sourcing or reorder. See [Request kinds](#request-kinds). One of `SOURCING`, `REORDER`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Request status. See [Request statuses](#request-statuses). One of `SUBMITTED`, `IN_PROGRESS`, `QUOTED`, `DONE`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `itemCount` | integer | Number of products in the request. |
| `createdAt` | string (date-time) | When you submitted it. |
| `updatedAt` | string (date-time) | When it last changed. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/requests?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/requests?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/requests?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "id": "cm3r8eq0s0002src2a3s4d5g",
      "number": "R2611090002",
      "kind": "REORDER",
      "kindLabel": "Reorder",
      "status": "SUBMITTED",
      "statusLabel": "Submitted",
      "itemCount": 1,
      "createdAt": "2026-11-09T06:00:00.000Z",
      "updatedAt": "2026-11-09T06:00:00.000Z"
    },
    {
      "id": "cm3r8eq0s0001src2a3s4d5f",
      "number": "R2611090001",
      "kind": "SOURCING",
      "kindLabel": "Sourcing request",
      "status": "SUBMITTED",
      "statusLabel": "Submitted",
      "itemCount": 1,
      "createdAt": "2026-11-09T06:00:00.000Z",
      "updatedAt": "2026-11-09T06:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

## Get a sourcing or reorder request

`GET /v1/requests/{id}`

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/requests/{id}` |
| Permission | `requests:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Request id, from [`GET /v1/requests`](https://docs.rephut.com/developers/reference/requests#list-sourcing-and-reorder-requests). An id that doesn't exist, isn't yours or isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Request id. |
| `number` | string | Our request number. |
| `kind` | string | Sourcing or reorder. See [Request kinds](#request-kinds). One of `SOURCING`, `REORDER`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Request status. See [Request statuses](#request-statuses). One of `SUBMITTED`, `IN_PROGRESS`, `QUOTED`, `DONE`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `itemCount` | integer | Number of products in the request. |
| `createdAt` | string (date-time) | When you submitted it. |
| `updatedAt` | string (date-time) | When it last changed. |
| `purpose` | string | What the goods are for. See [Purposes](#purposes). One of `DROPSHIP_STOCK`, `SHIP_TO_ME`, `AMAZON_FBA`. |
| `purposeLabel` | string | English text for display. It may change; rely on the code next to it. |
| `countryCode` | string or null | Destination country of a sourcing request; null for reorders. |
| `neededBy` | string (date) or null | When you need the goods (YYYY-MM-DD, China time); null when you gave no date. |
| `note` | string | Your note. |
| `staffReply` | string | Our reply; empty until we reply. |
| `cancelReason` | string | Why the request was cancelled; empty otherwise. |
| `cancelledByCustomer` | boolean | `true` when you withdrew it. |
| `canCancel` | boolean | `true` while you can still withdraw it. Withdraw requests in the portal; the API can't withdraw them. |
| `quoteId` | string or null | Our quote for this request; null until we send one. Fetch it with [`GET /v1/quotes/{id}`](https://docs.rephut.com/developers/reference/quotes#get-a-quote). |
| `quoteNumber` | string or null | Quote number; null until we send one. |
| `purchaseOrderId` | string or null | The purchase order made from this request; null until there is one. Fetch it with [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order). |
| `purchaseOrderNumber` | string or null | Purchase order number; null until there is one. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `totalCents` | integer or null | Reorders only: agreed price times quantity. |
| `items` | array of objects | Products in the request. |
| `items[].title` | string | Product name. |
| `items[].productUrl` | string | Product link you gave (sourcing). |
| `items[].specs` | string | Details you gave: size, colour, material. |
| `items[].qty` | integer | Quantity. |
| `items[].targetPriceCents` | integer or null | Your target unit price in US cents; null when none. |
| `items[].sku` | string | Our SKU (reorders); empty otherwise. |
| `items[].agreedPriceCents` | integer or null | Your agreed unit price in US cents (reorders); null otherwise. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/requests/cm3r8eq0s0001src2a3s4d5f' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/requests/cm3r8eq0s0001src2a3s4d5f", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/requests/cm3r8eq0s0001src2a3s4d5f",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3r8eq0s0001src2a3s4d5f",
    "number": "R2611090001",
    "kind": "SOURCING",
    "kindLabel": "Sourcing request",
    "status": "SUBMITTED",
    "statusLabel": "Submitted",
    "itemCount": 1,
    "createdAt": "2026-11-09T06:00:00.000Z",
    "updatedAt": "2026-11-09T06:00:00.000Z",
    "purpose": "DROPSHIP_STOCK",
    "purposeLabel": "Dropshipping stock",
    "countryCode": "US",
    "neededBy": "2026-12-01",
    "note": "Looking for a supplier with fast handling.",
    "staffReply": "",
    "cancelReason": "",
    "cancelledByCustomer": false,
    "canCancel": true,
    "quoteId": null,
    "quoteNumber": null,
    "purchaseOrderId": null,
    "purchaseOrderNumber": null,
    "currency": "USD",
    "totalCents": null,
    "items": [
      {
        "title": "Bamboo cutting board",
        "productUrl": "https://www.example.com/products/bamboo-board",
        "specs": "38 x 25 cm, with juice groove",
        "qty": 300,
        "targetPriceCents": 250,
        "sku": "",
        "agreedPriceCents": null
      }
    ]
  }
}
```

## Ask us to source new products

`POST /v1/requests/sourcing`

Submits a sourcing request like the portal's New request form. Give a product link for each product (the API can't upload images). We reply with a quote: follow it with GET /v1/requests/{id}. Send an Idempotency-Key so a retry can't submit it twice.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/requests/sourcing` |
| Permission | `requests:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Required |
| Success | 201 Created |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | Yes | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

A JSON object. Fields not listed here are ignored.

| Field | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | Yes | Destination country, two-letter code such as US. Pattern: `^[A-Z]{2}$`. |
| `purpose` | string | Yes | What the goods are for: DROPSHIP_STOCK, SHIP_TO_ME, AMAZON_FBA. One of `DROPSHIP_STOCK`, `SHIP_TO_ME`, `AMAZON_FBA`. |
| `neededBy` | string or null | No | When you need the goods, YYYY-MM-DD; null if there is no date. Default: `null`. |
| `note` | string | No | Anything else we should know. Up to 1,000 characters. Default: `""`. |
| `items` | array of objects | Yes | Products you want us to source. 1 to 20 items. |
| `items[].productUrl` | string | Yes | Link to the product you want, starting with http:// or https://. Up to 1,000 characters. |
| `items[].title` | string | Yes | Product name. 1 to 200 characters. |
| `items[].specs` | string | No | Size, colour, material and other details. Up to 1,000 characters. Default: `""`. |
| `items[].sourceCustomerSku` | string | No | Your SKU for the product, if you have one. Up to 100 characters. Default: `""`. |
| `items[].qty` | integer | Yes | Quantity you want. From 1 to 1,000,000. |
| `items[].targetPriceCents` | integer or null | No | Target unit price in US cents; null if you have none. From 0 to 999,999,999. Default: `null`. |

### Response

`201` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Request id. |
| `number` | string | Our request number. |
| `kind` | string | Sourcing or reorder. See [Request kinds](#request-kinds). One of `SOURCING`, `REORDER`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Request status. See [Request statuses](#request-statuses). One of `SUBMITTED`, `IN_PROGRESS`, `QUOTED`, `DONE`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `itemCount` | integer | Number of products in the request. |
| `createdAt` | string (date-time) | When you submitted it. |
| `updatedAt` | string (date-time) | When it last changed. |
| `purpose` | string | What the goods are for. See [Purposes](#purposes). One of `DROPSHIP_STOCK`, `SHIP_TO_ME`, `AMAZON_FBA`. |
| `purposeLabel` | string | English text for display. It may change; rely on the code next to it. |
| `countryCode` | string or null | Destination country of a sourcing request; null for reorders. |
| `neededBy` | string (date) or null | When you need the goods (YYYY-MM-DD, China time); null when you gave no date. |
| `note` | string | Your note. |
| `staffReply` | string | Our reply; empty until we reply. |
| `cancelReason` | string | Why the request was cancelled; empty otherwise. |
| `cancelledByCustomer` | boolean | `true` when you withdrew it. |
| `canCancel` | boolean | `true` while you can still withdraw it. Withdraw requests in the portal; the API can't withdraw them. |
| `quoteId` | string or null | Our quote for this request; null until we send one. Fetch it with [`GET /v1/quotes/{id}`](https://docs.rephut.com/developers/reference/quotes#get-a-quote). |
| `quoteNumber` | string or null | Quote number; null until we send one. |
| `purchaseOrderId` | string or null | The purchase order made from this request; null until there is one. Fetch it with [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order). |
| `purchaseOrderNumber` | string or null | Purchase order number; null until there is one. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `totalCents` | integer or null | Reorders only: agreed price times quantity. |
| `items` | array of objects | Products in the request. |
| `items[].title` | string | Product name. |
| `items[].productUrl` | string | Product link you gave (sourcing). |
| `items[].specs` | string | Details you gave: size, colour, material. |
| `items[].qty` | integer | Quantity. |
| `items[].targetPriceCents` | integer or null | Your target unit price in US cents; null when none. |
| `items[].sku` | string | Our SKU (reorders); empty otherwise. |
| `items[].agreedPriceCents` | integer or null | Your agreed unit price in US cents (reorders); null otherwise. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `idempotency_key_required` | 400 | This request needs an Idempotency-Key header. |
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `unknown_country` | 422 | Choose your country from the list. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/requests/sourcing' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: 7f3e9b21-0c4d-4a8e-b5f6-1e2d3c4b5a69' \
  -d '{
  "countryCode": "US",
  "purpose": "DROPSHIP_STOCK",
  "neededBy": "2026-12-01",
  "note": "Looking for a supplier with fast handling.",
  "items": [
    {
      "productUrl": "https://www.example.com/products/bamboo-board",
      "title": "Bamboo cutting board",
      "specs": "38 x 25 cm, with juice groove",
      "sourceCustomerSku": "",
      "qty": 300,
      "targetPriceCents": 250
    }
  ]
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/requests/sourcing", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "7f3e9b21-0c4d-4a8e-b5f6-1e2d3c4b5a69",
  },
  body: JSON.stringify({
    "countryCode": "US",
    "purpose": "DROPSHIP_STOCK",
    "neededBy": "2026-12-01",
    "note": "Looking for a supplier with fast handling.",
    "items": [
      {
        "productUrl": "https://www.example.com/products/bamboo-board",
        "title": "Bamboo cutting board",
        "specs": "38 x 25 cm, with juice groove",
        "sourceCustomerSku": "",
        "qty": 300,
        "targetPriceCents": 250
      }
    ]
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/requests/sourcing",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "7f3e9b21-0c4d-4a8e-b5f6-1e2d3c4b5a69",
    },
    json={
        "countryCode": "US",
        "purpose": "DROPSHIP_STOCK",
        "neededBy": "2026-12-01",
        "note": "Looking for a supplier with fast handling.",
        "items": [
            {
                "productUrl": "https://www.example.com/products/bamboo-board",
                "title": "Bamboo cutting board",
                "specs": "38 x 25 cm, with juice groove",
                "sourceCustomerSku": "",
                "qty": 300,
                "targetPriceCents": 250,
            },
        ],
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=201
{
  "success": true,
  "data": {
    "id": "cm3r8eq0s0001src2a3s4d5f",
    "number": "R2611090001",
    "kind": "SOURCING",
    "kindLabel": "Sourcing request",
    "status": "SUBMITTED",
    "statusLabel": "Submitted",
    "itemCount": 1,
    "createdAt": "2026-11-09T06:00:00.000Z",
    "updatedAt": "2026-11-09T06:00:00.000Z",
    "purpose": "DROPSHIP_STOCK",
    "purposeLabel": "Dropshipping stock",
    "countryCode": "US",
    "neededBy": "2026-12-01",
    "note": "Looking for a supplier with fast handling.",
    "staffReply": "",
    "cancelReason": "",
    "cancelledByCustomer": false,
    "canCancel": true,
    "quoteId": null,
    "quoteNumber": null,
    "purchaseOrderId": null,
    "purchaseOrderNumber": null,
    "currency": "USD",
    "totalCents": null,
    "items": [
      {
        "title": "Bamboo cutting board",
        "productUrl": "https://www.example.com/products/bamboo-board",
        "specs": "38 x 25 cm, with juice groove",
        "qty": 300,
        "targetPriceCents": 250,
        "sku": "",
        "agreedPriceCents": null
      }
    ]
  }
}
```

## Ask us to restock products at your agreed prices

`POST /v1/requests/reorder`

Submits a reorder request like the portal's Reorder form. Only products with an agreed price can be reordered (canReorder in GET /v1/products); others return 422 product_not_reorderable. Send an Idempotency-Key so a retry can't submit it twice.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/requests/reorder` |
| Permission | `requests:write` |
| Access | Write: counts towards the write limits and is refused with `account_on_hold` while your account is on hold |
| Idempotency-Key | Required |
| Success | 201 Created |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | Yes | 1 to 255 visible ASCII characters, new for each new request. See [Idempotency](https://docs.rephut.com/developers/idempotency). |

### Request body

A JSON object. Fields not listed here are ignored.

| Field | Type | Required | Description |
|---|---|---|---|
| `purpose` | string | Yes | What the goods are for: DROPSHIP_STOCK, SHIP_TO_ME, AMAZON_FBA. One of `DROPSHIP_STOCK`, `SHIP_TO_ME`, `AMAZON_FBA`. |
| `note` | string | No | Anything else we should know. Up to 1,000 characters. Default: `""`. |
| `items` | array of objects | Yes | Products you can reorder (canReorder in GET /v1/products), each once, with quantities. 1 to 20 items. |
| `items[].productId` | string | Yes | Our product id; the product must have `canReorder: true`. Not empty. |
| `items[].qty` | integer | Yes | Quantity to buy. From 1 to 1,000,000. |

### Response

`201` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Request id. |
| `number` | string | Our request number. |
| `kind` | string | Sourcing or reorder. See [Request kinds](#request-kinds). One of `SOURCING`, `REORDER`. |
| `kindLabel` | string | English text for display. It may change; rely on the code next to it. |
| `status` | string | Request status. See [Request statuses](#request-statuses). One of `SUBMITTED`, `IN_PROGRESS`, `QUOTED`, `DONE`, `CANCELLED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `itemCount` | integer | Number of products in the request. |
| `createdAt` | string (date-time) | When you submitted it. |
| `updatedAt` | string (date-time) | When it last changed. |
| `purpose` | string | What the goods are for. See [Purposes](#purposes). One of `DROPSHIP_STOCK`, `SHIP_TO_ME`, `AMAZON_FBA`. |
| `purposeLabel` | string | English text for display. It may change; rely on the code next to it. |
| `countryCode` | string or null | Destination country of a sourcing request; null for reorders. |
| `neededBy` | string (date) or null | When you need the goods (YYYY-MM-DD, China time); null when you gave no date. |
| `note` | string | Your note. |
| `staffReply` | string | Our reply; empty until we reply. |
| `cancelReason` | string | Why the request was cancelled; empty otherwise. |
| `cancelledByCustomer` | boolean | `true` when you withdrew it. |
| `canCancel` | boolean | `true` while you can still withdraw it. Withdraw requests in the portal; the API can't withdraw them. |
| `quoteId` | string or null | Our quote for this request; null until we send one. Fetch it with [`GET /v1/quotes/{id}`](https://docs.rephut.com/developers/reference/quotes#get-a-quote). |
| `quoteNumber` | string or null | Quote number; null until we send one. |
| `purchaseOrderId` | string or null | The purchase order made from this request; null until there is one. Fetch it with [`GET /v1/purchase-orders/{id}`](https://docs.rephut.com/developers/reference/purchase-orders#get-a-purchase-order). |
| `purchaseOrderNumber` | string or null | Purchase order number; null until there is one. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `totalCents` | integer or null | Reorders only: agreed price times quantity. |
| `items` | array of objects | Products in the request. |
| `items[].title` | string | Product name. |
| `items[].productUrl` | string | Product link you gave (sourcing). |
| `items[].specs` | string | Details you gave: size, colour, material. |
| `items[].qty` | integer | Quantity. |
| `items[].targetPriceCents` | integer or null | Your target unit price in US cents; null when none. |
| `items[].sku` | string | Our SKU (reorders); empty otherwise. |
| `items[].agreedPriceCents` | integer or null | Your agreed unit price in US cents (reorders); null otherwise. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `idempotency_key_required` | 400 | This request needs an Idempotency-Key header. |
| `invalid_idempotency_key` | 400 | Idempotency-Key must be 1 to 255 visible ASCII characters. |
| `invalid_json` | 400 | The request body is not valid JSON. |
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `account_on_hold` | 403 | The account is on hold. Writes are refused; reads still work. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `request_in_progress` | 409 | A request with this Idempotency-Key is still running or its result is unknown. |
| `payload_too_large` | 413 | The request body is larger than 1 MB. |
| `unsupported_media_type` | 415 | The request body must be sent as application/json. |
| `idempotency_key_reused` | 422 | This Idempotency-Key was already used with a different request. |
| `product_not_reorderable` | 422 | One of the products is no longer available to reorder. Please refresh the page and try again. |
| `request_rejected` | 422 | The request was rejected by a business rule. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl -X POST 'https://api.rephut.com/v1/requests/reorder' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: e8d7c6b5-a4f3-4e21-9d0c-8b7a6f5e4d32' \
  -d '{
  "purpose": "DROPSHIP_STOCK",
  "note": "",
  "items": [
    {
      "productId": "cm3p4r0d0001xyz7k2m9q8w1",
      "qty": 200
    }
  ]
}'
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/requests/reorder", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "e8d7c6b5-a4f3-4e21-9d0c-8b7a6f5e4d32",
  },
  body: JSON.stringify({
    "purpose": "DROPSHIP_STOCK",
    "note": "",
    "items": [
      {
        "productId": "cm3p4r0d0001xyz7k2m9q8w1",
        "qty": 200
      }
    ]
  }),
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.post(
    "https://api.rephut.com/v1/requests/reorder",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
        "Idempotency-Key": "e8d7c6b5-a4f3-4e21-9d0c-8b7a6f5e4d32",
    },
    json={
        "purpose": "DROPSHIP_STOCK",
        "note": "",
        "items": [
            {
                "productId": "cm3p4r0d0001xyz7k2m9q8w1",
                "qty": 200,
            },
        ],
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=201
{
  "success": true,
  "data": {
    "id": "cm3r8eq0s0002src2a3s4d5g",
    "number": "R2611090002",
    "kind": "REORDER",
    "kindLabel": "Reorder",
    "status": "SUBMITTED",
    "statusLabel": "Submitted",
    "itemCount": 1,
    "createdAt": "2026-11-09T06:00:00.000Z",
    "updatedAt": "2026-11-09T06:00:00.000Z",
    "purpose": "DROPSHIP_STOCK",
    "purposeLabel": "Dropshipping stock",
    "countryCode": null,
    "neededBy": null,
    "note": "",
    "staffReply": "",
    "cancelReason": "",
    "cancelledByCustomer": false,
    "canCancel": true,
    "quoteId": null,
    "quoteNumber": null,
    "purchaseOrderId": null,
    "purchaseOrderNumber": null,
    "currency": "USD",
    "totalCents": 77000,
    "items": [
      {
        "title": "Cotton crew neck T-shirt",
        "productUrl": "",
        "specs": "Black / M",
        "qty": 200,
        "targetPriceCents": null,
        "sku": "FB-10231-BLK-M",
        "agreedPriceCents": 385
      }
    ]
  }
}
```

---

Source: https://docs.rephut.com/developers/reference/quotes

# Quotes

A quote is our offer for a sourcing request: a price for each product and shipping options to your destination. When we change a quote we send a new version: it has a new `id`, the same `number` and a higher `version`, and the old version becomes `SUPERSEDED` with `newerVersionId` pointing to the new one. The list shows the version you can see of each quote number, newest quote number first.

Webhook `quote.created` tells you about every new quote and every new version. Accept or decline quotes in the portal; the API can't do that yet. Accepting writes the agreed prices into My products (the products then show `price.kind` `AGREED` and can be restocked) and moves the request on to `DONE`; a purchase order can follow. Declining the latest version sends the request back to `IN_PROGRESS`. There is no `updatedSince` here: use webhooks and GET, or read the first pages again to find new ones (the list is newest first). See [Incremental sync](https://docs.rephut.com/developers/incremental-sync).

## Quote statuses

| Value | Meaning |
|---|---|
| `AWAITING` | Awaiting your decision. Accept or decline it in the portal. |
| `UPDATING` | We are preparing a new version. |
| `SUPERSEDED` | Replaced by a newer version; `newerVersionId` points to it. |
| `ACCEPTED` | You accepted it. |
| `DECLINED` | You declined it. |
| `EXPIRED` | `validUntil` passed without a decision. |

## List quotes

`GET /v1/quotes`

The version you can see of each quote number. Newest quote number first.

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/quotes` |
| Permission | `quotes:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number. See [Pagination](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, a list of objects with the fields below (up to one page), and `meta` with `total`, `page`, `limit` and `pageCount`. See [Pagination](https://docs.rephut.com/developers/pagination).

| Field | Type | Description |
|---|---|---|
| `id` | string | Quote id. Each version of a quote has its own id. |
| `number` | string | Our quote number; the same for every version. |
| `version` | integer | Version number, starting at 1. |
| `status` | string | Quote status. See [Quote statuses](#quote-statuses). One of `AWAITING`, `UPDATING`, `SUPERSEDED`, `ACCEPTED`, `DECLINED`, `EXPIRED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `issuedAt` | string (date-time) | When we sent this version. |
| `validUntil` | string (date-time) | The prices are valid until this time. |
| `itemCount` | integer | Number of products. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `goodsCents` | integer | Total for the goods in US cents, without shipping. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/quotes?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/quotes?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/quotes?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": [
    {
      "id": "cm3u2qt0e0001quo6h7j8k9l",
      "number": "Q2611100001",
      "version": 1,
      "status": "AWAITING",
      "statusLabel": "Awaiting your decision",
      "issuedAt": "2026-11-10T07:00:00.000Z",
      "validUntil": "2026-11-17T07:00:00.000Z",
      "itemCount": 1,
      "currency": "USD",
      "goodsCents": 72000
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}
```

## Get a quote

`GET /v1/quotes/{id}`

| Property | Value |
|---|---|
| URL | `https://api.rephut.com/v1/quotes/{id}` |
| Permission | `quotes:read` |
| Access | Read: counts towards the read limit and works while your account is on hold |
| Idempotency-Key | Not used |
| Success | 200 OK |

### Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Quote id, from [`GET /v1/quotes`](https://docs.rephut.com/developers/reference/quotes#list-quotes) or `quoteId` of a request. An id that doesn't exist, isn't yours or isn't a valid id returns 404 `not_found`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/authentication). |

### Response

`200` with `data`, an object with the fields below.

| Field | Type | Description |
|---|---|---|
| `id` | string | Quote id. Each version of a quote has its own id. |
| `number` | string | Our quote number; the same for every version. |
| `version` | integer | Version number, starting at 1. |
| `status` | string | Quote status. See [Quote statuses](#quote-statuses). One of `AWAITING`, `UPDATING`, `SUPERSEDED`, `ACCEPTED`, `DECLINED`, `EXPIRED`. |
| `statusLabel` | string | English text for display. It may change; rely on the code next to it. |
| `canDecide` | boolean | `true` while you can accept or decline it. Accept or decline quotes in the portal; the API can't do it yet. |
| `issuedAt` | string (date-time) | When we sent this version. |
| `validUntil` | string (date-time) | The prices are valid until this time. |
| `decidedAt` | string (date-time) or null | When it was accepted or declined (by you or by our team for you); null before that. |
| `destinationCountryCode` | string | Two-letter destination country code. |
| `destination` | string | Destination in English. |
| `paymentMethodName` | string or null | Payment method for this quote; null when none. |
| `note` | string | Our note. |
| `customerFeedback` | string | Feedback you sent us about this quote; empty when none. |
| `currency` | string | Currency of every amount. Always `USD`. |
| `items` | array of objects | Quoted products. |
| `items[].sku` | string | Our SKU. |
| `items[].name` | string | Product name in English. |
| `items[].attributes` | string | Variant details in English. |
| `items[].customerSku` | string | Your SKU for the product; empty when none. |
| `items[].qty` | integer | Quantity. |
| `items[].unitPriceCents` | integer | Unit price in US cents. |
| `items[].amountCents` | integer | Line amount in US cents. |
| `goodsCents` | integer | Total for the goods in US cents, without shipping. |
| `shippingOptions` | array of objects | Shipping options we quoted. |
| `shippingOptions[].label` | string | Name of the option. |
| `shippingOptions[].transitDays` | string | Delivery time, for example 7-12 days. |
| `shippingOptions[].shippingCents` | integer | Shipping in US cents. |
| `shippingOptions[].totalCents` | integer | Goods plus shipping, in US cents. |
| `shippingOptions[].shippingMaxCents` | integer or null | Upper bound when shipping depends on the postcode; otherwise null. |
| `shippingOptions[].totalMaxCents` | integer or null | Upper bound of the total when shipping depends on the postal code; otherwise null. |
| `newerVersionId` | string or null | Set when a newer version replaced this one. |

### Errors

| Code | HTTP status | Meaning |
|---|---|---|
| `invalid_api_key` | 401 | The API key is missing, malformed, revoked or no longer valid. |
| `account_action_required` | 403 | Sign in to the portal and finish the required account steps first. |
| `api_not_enabled` | 403 | API access is not enabled for this account. |
| `insufficient_scope` | 403 | The API key does not have the permission this call needs. |
| `not_found` | 404 | The resource does not exist or does not belong to this account. |
| `validation_failed` | 422 | The input is not valid. `details` lists each field and the reason. |
| `rate_limited` | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
| `internal_error` | 500 | Unexpected error. Quote X-Request-Id when you contact support. |

Handle errors by `code`. See [Errors](https://docs.rephut.com/developers/errors).

```bash example=curl
curl 'https://api.rephut.com/v1/quotes/cm3u2qt0e0001quo6h7j8k9l' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"
```

```js example=node
const response = await fetch("https://api.rephut.com/v1/quotes/cm3u2qt0e0001quo6h7j8k9l", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

```python example=python
import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/quotes/cm3u2qt0e0001quo6h7j8k9l",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

```json example=response status=200
{
  "success": true,
  "data": {
    "id": "cm3u2qt0e0001quo6h7j8k9l",
    "number": "Q2611100001",
    "version": 1,
    "status": "AWAITING",
    "statusLabel": "Awaiting your decision",
    "canDecide": true,
    "issuedAt": "2026-11-10T07:00:00.000Z",
    "validUntil": "2026-11-17T07:00:00.000Z",
    "decidedAt": null,
    "destinationCountryCode": "US",
    "destination": "United States",
    "paymentMethodName": null,
    "note": "Price includes a branded sleeve.",
    "customerFeedback": "",
    "currency": "USD",
    "items": [
      {
        "sku": "FB-10412-NAT",
        "name": "Bamboo cutting board",
        "attributes": "38 x 25 cm",
        "customerSku": "",
        "qty": 300,
        "unitPriceCents": 240,
        "amountCents": 72000
      }
    ],
    "goodsCents": 72000,
    "shippingOptions": [
      {
        "label": "US Sea Freight",
        "transitDays": "30-40 days",
        "shippingCents": 21000,
        "totalCents": 93000,
        "shippingMaxCents": null,
        "totalMaxCents": null
      }
    ],
    "newerVersionId": null
  }
}
```

---

Source: https://docs.rephut.com/developers/webhooks

# Webhooks

Webhooks tell your system when something changes, so you don't have to poll. When an event you subscribed to happens, we send an HTTPS `POST` to your endpoint with a small JSON body: the event type, the id of what changed and its new status. Fetch the details with the API.

## Set up an endpoint

1. In the portal, open **Settings → API access** and go to **Add a webhook endpoint**.
2. Enter the endpoint URL: a public `https://` address of up to 2,000 characters, without a user name, password or `#` part. `localhost`, single-word host names, private and local IP addresses, and names ending in `.local`, `.internal`, `.lan`, `.localhost` or `.home.arpa` are refused.
3. Optionally add a description of up to 100 characters.
4. Tick the events you want: see [Webhook events](https://docs.rephut.com/developers/webhooks/events).
5. Click **Add endpoint**, then copy the signing secret (`whsec_...`) straight away. It is shown only once. Store it like a password.

You must have signed in within the last 10 minutes to add an endpoint or create a new secret. An account can have up to 5 endpoints, including turned-off ones. Webhooks need API access to be on for your account.

## Manage endpoints

Open an endpoint in **Settings → API access** to:

- change its URL, description and events (**Save changes**);
- **Create a new secret**: it replaces the old secret at once, with no overlap, so update your receiver straight after;
- **Send test event**: see [Webhook delivery and retries](https://docs.rephut.com/developers/webhooks/delivery#test-events);
- **Turn off** and **Turn on**;
- **Delete endpoint**;
- see **Recent deliveries**: the last 50 deliveries with their status, attempts and your endpoint's answer.

While your account is on hold you can't add or change endpoints or turn them on. You can still turn them off, delete them, create a new secret and send test events.

## What a webhook looks like

```text
POST /your/webhook/path HTTP/1.1
Content-Type: application/json
User-Agent: Fulfillbot-Webhooks/1.0
X-Webhook-Id: evt_3f9a1c2b7d4e5f60718293a4
X-Webhook-Event: order.status_changed
X-Webhook-Attempt: 1
X-Webhook-Signature: t=1762653600,v1=78e8462fdd961bd012879276064959675d3a21748eb85da05b69fb9f18e51c0d

{"id":"evt_3f9a1c2b7d4e5f60718293a4","type":"order.status_changed","createdAt":"2026-11-09T02:00:00.000Z","data":{"id":"cm3o7rd0e0001h2j3k4l5m6n","status":"SHIPPED"}}
```

This example is signed with the example secret `whsec_example_only_do_not_use`. Its timestamp is in the past, so to try your verification code with it, pass the example's time (`1762653600`) as the current time: the samples on [Verifying webhook signatures](https://docs.rephut.com/developers/webhooks/signatures) take an optional `now` argument for this. Never do that in production.

The table below describes the body of this example. `type` and `data` differ per event: see [Webhook events](https://docs.rephut.com/developers/webhooks/events).

| Field | Type | Description |
|---|---|---|
| `id` | string | Event id. Retries and every endpoint get the same id; use it to skip duplicates. |
| `type` | string | The event type. Always `order.status_changed`. |
| `createdAt` | string (date-time) | When the change happened (ISO 8601, UTC). |
| `data` | object | What changed: the id of the resource and its status after the change. For `webhook.test`, `id` is the endpoint id and `status` is `TEST`. |
| `data.id` | string | Order id. Fetch it with GET /v1/orders/{id}. |
| `data.status` | string | The status after the change (uppercase code). One of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`. |

Payloads never contain personal data, amounts, images or file links. Fetch the resource with its `GET` endpoint for the details.

## Headers

| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `User-Agent` | `Fulfillbot-Webhooks/1.0` |
| `X-Webhook-Id` | The event id. The same on every retry and for every endpoint that gets the event; use it to skip duplicates. |
| `X-Webhook-Event` | The event type, for example `order.status_changed`. |
| `X-Webhook-Attempt` | Which attempt this is, 1 to 6. |
| `X-Webhook-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>`. See [Verifying webhook signatures](https://docs.rephut.com/developers/webhooks/signatures). |

## Next

- [Webhook events](https://docs.rephut.com/developers/webhooks/events): what each event means and when it is sent.
- [Verifying webhook signatures](https://docs.rephut.com/developers/webhooks/signatures): check that a request really comes from us.
- [Webhook delivery and retries](https://docs.rephut.com/developers/webhooks/delivery): timeouts, retries, ordering and duplicates.
- [Handle webhooks reliably](https://docs.rephut.com/developers/guides/reliable-webhooks): a design that doesn't lose events.

---

Source: https://docs.rephut.com/developers/webhooks/events

# Webhook events

You choose which events each endpoint receives. Every event has the same payload shape (see [Webhooks](https://docs.rephut.com/developers/webhooks)): `data.id` is the id of what changed and `data.status` its status after the change.

### `order.status_changed`

Shown in the portal as **Order status changed**. An order was created or its status changed, for example to RESERVED, WEIGHED, SHIPPED or CANCELLED.

- **Sent when:** An order is created (its first status) and every time its status changes afterwards, whether the change came from the API, the portal, a connected store or our team.
- **`data.id`:** Order id. Fetch it with GET /v1/orders/{id}.
- **`data.status`:** one of `NEEDS_ATTENTION`, `READY`, `BACKORDERED`, `RESERVED`, `WEIGHED`, `SHIPPED`, `CANCELLED`.

### `order.awaiting_payment`

Shown in the portal as **Order needs payment to ship**. Your available balance didn't cover the shipping and handling fee when the parcel was weighed. The order waits for a top-up; GET the order for the amount due.

- **Sent when:** Our warehouse weighed the parcel and your available balance didn't cover the shipping and handling fee: sent once per unpaid round, at the same time as the portal notification. A re-weigh in the same round that changes the amount due sends nothing; GET the order for the current amount.
- **`data.id`:** Order id. GET /v1/orders/{id} shows the amount due.
- **`data.status`:** Always `RESERVED`.

### `purchase_order.status_changed`

Shown in the portal as **Purchase order status changed**. A purchase order was created or its status changed.

- **Sent when:** A purchase order is created (status `AWAITING_PAYMENT`) and every time its status changes afterwards.
- **`data.id`:** Purchase order id. Fetch it with GET /v1/purchase-orders/{id}.
- **`data.status`:** one of `AWAITING_PAYMENT`, `DEPOSIT_PAID`, `PAID`, `PURCHASING`, `ORDERED`, `IN_TRANSIT`, `PARTIALLY_ARRIVED`, `ARRIVED`, `STORED`, `COMPLETED`, `CANCELLED`.

### `shipment.status_changed`

Shown in the portal as **Shipment status changed**. A shipment was created by you in the portal, sent to you for confirmation, or changed status.

- **Sent when:** A shipment you can see is created or changes status: one you asked for, or one we prepared and sent you (we don't send events for our drafts).
- **`data.id`:** Shipment id. Fetch it with GET /v1/shipments/{id}.
- **`data.status`:** one of `DRAFT`, `PENDING_CONFIRMATION`, `AWAITING_PAYMENT`, `PAID`, `SHIPPED`, `CANCELLED`.

### `shipment.tracking_updated`

Shown in the portal as **Shipment tracking numbers added**. Tracking numbers were added to a shipment. GET the shipment to read them.

- **Sent when:** Tracking numbers are added to a shipment (today this happens when it ships).
- **`data.id`:** Shipment id. GET /v1/shipments/{id} lists the tracking numbers.
- **`data.status`:** Always `SHIPPED`.

### `quote.created`

Shown in the portal as **New quote ready**. We sent you a quote. A new version of a quote has a new id.

- **Sent when:** We send you a quote, and again for each new version (a new version has a new id). The status is always `AWAITING`.
- **`data.id`:** Quote id. Fetch it with GET /v1/quotes/{id}.
- **`data.status`:** Always `AWAITING`.

### `wallet.top_up_approved`

Shown in the portal as **Top-up approved**. A top-up was approved and credited to your wallet.

- **Sent when:** We approve a pending top-up, or record a top-up for you directly. The status is always `CONFIRMED`.
- **`data.id`:** Top-up id, as listed by GET /v1/wallet/top-ups.
- **`data.status`:** Always `CONFIRMED`.

## Test events

`webhook.test` is sent only when you click **Send test event** in the portal. Its `data.id` is the endpoint's id and `data.status` is `TEST`. You can't subscribe to it. See [Webhook delivery and retries](https://docs.rephut.com/developers/webhooks/delivery#test-events).

## Good to know

- Events cover changes from every source: the API, the portal, connected stores and our team.
- A newly created resource and a status change look the same: the payload doesn't say what the status was before.
- If something changes and changes back within one update, no event is sent.
- Events are recorded only while API access is on for your account, for endpoints that are on and subscribed to that event.

No event is sent for:

- Changing an order's tracking number after it shipped.
- Accepting or declining a quote.
- Rejecting a top-up.
- Voiding an approved top-up.
- A quote expiring or becoming `UPDATING` or `SUPERSEDED`: these are worked out when you read the quote, not written as changes.

---

Source: https://docs.rephut.com/developers/webhooks/signatures

# Verifying webhook signatures

Every webhook request carries `X-Webhook-Signature: t=<unix seconds>,v1=<hex>`. Check it before you trust a request: anyone can send a `POST` to your endpoint.

## How the signature works

- `t` is when we sent this attempt, as Unix time in seconds. Each retry is signed again with a new `t`.
- `v1` is the HMAC-SHA256 of the string `<t>.<raw request body>`, keyed with the endpoint's signing secret (the whole `whsec_...` string, as UTF-8), written in lowercase hex.

To verify a request:

1. Read the raw request body exactly as received, **before** parsing the JSON. JSON that you parse and serialise again won't match.
2. Split the header on `,` and `=` to get `t` and `v1`.
3. Reject the request if `t` is more than 5 minutes (300 seconds) away from your clock, so old requests can't be replayed. Keep your server clock in sync.
4. Compute the HMAC-SHA256 of `t`, a dot and the raw body with your secret, and compare it with `v1` in constant time.
5. If it doesn't match, answer `400` and ignore the request.

## Node.js

```js
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received (a string, before JSON parsing)
// now: Unix time in seconds, optional; pass 1762653600 to check the sample request in the docs
function isValidWebhook(secret, signatureHeader, rawBody, now = Date.now() / 1000) {
  const parts = new Map(
    signatureHeader.split(",").map((part) => {
      const index = part.indexOf("=");
      return index < 0 ? [part.trim(), ""] : [part.slice(0, index).trim(), part.slice(index + 1)];
    }),
  );
  const rawTimestamp = parts.get("t") ?? "";
  const given = parts.get("v1") ?? "";
  const timestamp = Number(rawTimestamp);
  if (!/^[0-9]+$/.test(rawTimestamp) || !Number.isSafeInteger(timestamp) || Math.abs(now - timestamp) > 300) return false;
  if (!/^[0-9a-f]{64}$/.test(given)) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  return timingSafeEqual(Buffer.from(given, "hex"), expected);
}
```

`rawBody` is the body as a string, exactly as received.

## Python

```python
import hashlib
import hmac
import re
import time


# raw_body: the request body exactly as received (bytes, before JSON parsing)
# now: Unix time in seconds, optional; pass 1762653600 to check the sample request in the docs
def is_valid_webhook(secret, signature_header, raw_body, now=None):
    if now is None:
        now = time.time()
    parts = {}
    for part in signature_header.split(","):
        key, _, value = part.partition("=")
        parts[key.strip()] = value
    timestamp = parts.get("t", "")
    given = parts.get("v1", "")
    if not re.fullmatch(r"[0-9]{1,16}", timestamp) or abs(now - int(timestamp)) > 300:
        return False
    if not re.fullmatch(r"[0-9a-f]{64}", given):
        return False
    signed = str(int(timestamp)).encode("utf-8") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, given)
```

`raw_body` is the body as bytes, exactly as received.

## Complete receivers

These minimal servers verify the signature, answer at once and skip duplicates. They read the secret from `FULFILLBOT_WEBHOOK_SECRET`. With a framework, make sure you get the raw body: for example `express.raw({ type: "application/json" })` in Express, or `request.get_data()` in Flask.

### Node.js receiver

```js
import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.FULFILLBOT_WEBHOOK_SECRET;
// Keep processed event ids in your database in production; a Set is lost on restart.
const seenEventIds = new Set();

function isValidWebhook(secret, signatureHeader, rawBody, now = Date.now() / 1000) {
  const parts = new Map(
    signatureHeader.split(",").map((part) => {
      const index = part.indexOf("=");
      return index < 0 ? [part.trim(), ""] : [part.slice(0, index).trim(), part.slice(index + 1)];
    }),
  );
  const rawTimestamp = parts.get("t") ?? "";
  const given = parts.get("v1") ?? "";
  const timestamp = Number(rawTimestamp);
  if (!/^[0-9]+$/.test(rawTimestamp) || !Number.isSafeInteger(timestamp) || Math.abs(now - timestamp) > 300) return false;
  if (!/^[0-9a-f]{64}$/.test(given)) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  return timingSafeEqual(Buffer.from(given, "hex"), expected);
}

// Set a body limit: reject oversized requests before they use your memory.
const MAX_BODY_BYTES = 1_000_000;

createServer((request, response) => {
  const chunks = [];
  let size = 0;
  request.on("data", (chunk) => {
    size += chunk.length;
    if (size <= MAX_BODY_BYTES) chunks.push(chunk);
  });
  request.on("end", () => {
    if (size > MAX_BODY_BYTES) {
      response.writeHead(413).end();
      return;
    }
    const rawBody = Buffer.concat(chunks).toString("utf8");
    if (!isValidWebhook(SECRET, request.headers["x-webhook-signature"] ?? "", rawBody)) {
      response.writeHead(400).end();
      return;
    }
    let event;
    try {
      event = JSON.parse(rawBody);
    } catch {
      response.writeHead(400).end();
      return;
    }
    // Answer within the timeout first; do slow work (such as GET calls) after answering or in a queue.
    response.writeHead(200).end();
    if (seenEventIds.has(event.id)) return;
    seenEventIds.add(event.id);
    console.log("Received", event.type, event.data.id, event.data.status);
  });
}).listen(8000);
```

### Python receiver

```python
import hashlib
import hmac
import re
import time
import json
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ["FULFILLBOT_WEBHOOK_SECRET"]
# Keep processed event ids in your database in production; a set is lost on restart.
seen_event_ids = set()


# raw_body: the request body exactly as received (bytes, before JSON parsing)
# now: Unix time in seconds, optional; pass 1762653600 to check the sample request in the docs
def is_valid_webhook(secret, signature_header, raw_body, now=None):
    if now is None:
        now = time.time()
    parts = {}
    for part in signature_header.split(","):
        key, _, value = part.partition("=")
        parts[key.strip()] = value
    timestamp = parts.get("t", "")
    given = parts.get("v1", "")
    if not re.fullmatch(r"[0-9]{1,16}", timestamp) or abs(now - int(timestamp)) > 300:
        return False
    if not re.fullmatch(r"[0-9a-f]{64}", given):
        return False
    signed = str(int(timestamp)).encode("utf-8") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, given)


# Set a body limit: reject oversized requests before reading them.
MAX_BODY_BYTES = 1_000_000


class WebhookHandler(BaseHTTPRequestHandler):
    def reply(self, status):
        self.send_response(status)
        self.send_header("Content-Length", "0")
        self.end_headers()

    def do_POST(self):
        length_header = self.headers.get("Content-Length", "")
        if not re.fullmatch(r"[0-9]{1,12}", length_header):
            self.reply(400)
            return
        length = int(length_header)
        if length > MAX_BODY_BYTES:
            self.reply(413)
            return
        raw_body = self.rfile.read(length)
        if not is_valid_webhook(SECRET, self.headers.get("X-Webhook-Signature", ""), raw_body):
            self.reply(400)
            return
        try:
            event = json.loads(raw_body)
        except ValueError:
            self.reply(400)
            return
        # Answer within the timeout first; do slow work after answering or in a queue.
        self.reply(200)
        if event["id"] in seen_event_ids:
            return
        seen_event_ids.add(event["id"])
        print("Received", event["type"], event["data"]["id"], event["data"]["status"])


HTTPServer(("", 8000), WebhookHandler).serve_forever()
```

## Rotating the secret

**Create a new secret** on the endpoint's page replaces the secret at once; requests signed with the old one stop at that moment. Update your receiver with the new secret straight after. Attempts that fail in between are retried ([Webhook delivery and retries](https://docs.rephut.com/developers/webhooks/delivery)) and are signed with the new secret.

---

Source: https://docs.rephut.com/developers/webhooks/delivery

# Webhook delivery and retries

## Answering

Answer with any `2xx` status within 10 seconds. We ignore the body of your answer, but it must not be larger than 64 KB. Everything else counts as a failed attempt: another status, a redirect (we don't follow redirects), a timeout, a connection or TLS error, or a larger answer.

Answer first and do the work afterwards, for example by putting the event on a queue.

## When events are sent

We look for new events every minute, so an event usually arrives within a minute of the change. An event is sent until your endpoint accepts it or the retries run out (so you may receive an event more than once). Every endpoint subscribed to the event gets its own deliveries.

## Retries

| Attempt | When | After the first attempt |
|---|---|---|
| 1 | Usually within a minute of the change | — |
| 2 | 1 minute after attempt 1 failed | about 1 minute |
| 3 | 5 minutes after attempt 2 failed | about 6 minutes |
| 4 | 25 minutes after attempt 3 failed | about 31 minutes |
| 5 | 125 minutes after attempt 4 failed | about 2 h 36 min |
| 6 | 625 minutes after attempt 5 failed | about 13 h 1 min |

There are at most 6 attempts. When the last one fails, the delivery is marked failed. `X-Webhook-Attempt` says which attempt a request is.

## Automatic turn-off

After 50 failed attempts in a row (attempts, not events; test events don't count), we turn the endpoint off, mark its open deliveries as failed and notify you in the portal. Fix your receiver, then click **Turn on**. Events from while the endpoint was off are not sent again: catch up with the API, for example with [Incremental sync](https://docs.rephut.com/developers/incremental-sync).

## When API access is off

No new events are recorded. Deliveries already waiting are paused and continue when API access is back on; anything still undelivered 24 hours after the event is marked expired.

## Order and duplicates

- Events arrive in no particular order. A later change can arrive before an earlier one, and a retry arrives after newer events.
- An event can arrive more than once, for example when your answer got lost. Every attempt and every endpoint gets the same event `id`, also in `X-Webhook-Id`. Store the ids you processed and skip repeats.
- Treat an event as a hint: fetch the resource with `GET` and act on what it says now, not on the event's `status`.

## Test events

**Send test event** on an endpoint's page sends a `webhook.test` event to that endpoint at once and shows the result. Test events are not retried and don't count towards turning the endpoint off. You can send one every 30 seconds per endpoint, also to an endpoint that is turned off.

## Delivery log

The endpoint's page shows the last 50 deliveries with the time, the event, the status (Queued, Retrying, Delivered or Failed), the number of attempts and your endpoint's answer. We keep events and deliveries for 30 days. Failure reasons:

| Shown in the delivery log | What it means |
|---|---|
| Your endpoint answered HTTP 500. | Your endpoint answered with a status that isn't 2xx. |
| Your endpoint didn't answer within 10 seconds. | No answer in time. Answer first, then do the work. |
| Your endpoint answered with a redirect. Redirects aren't followed. | We don't follow redirects. Register the final URL. |
| Your endpoint's response was larger than 64 KB. | Send a short body, or none. |
| We couldn't find this host. | The host name doesn't resolve. |
| We couldn't connect to your endpoint. | Connection refused, reset or TLS failed. |
| The URL resolves to a private or local address, so we didn't send it. | The host resolves to a private, local or link-local address. Endpoints must be public. |
| Not delivered within 24 hours. | The event couldn't be delivered within the delivery window. |
| The endpoint was turned off. | The endpoint was turned off before the event was delivered. |
| We couldn't send the request. | Any other failure. |

## Firewalls

The addresses we send from can change, so check the signature rather than allow-listing IP addresses. Requests carry `User-Agent: Fulfillbot-Webhooks/1.0`.

---

Source: https://docs.rephut.com/developers/guides/sync-orders

# Keep your orders in sync

This guide keeps a copy of your orders in your own system, up to date within about a minute, without losing changes.

## The design

1. **Webhooks for speed.** Subscribe an endpoint to `order.status_changed` and `order.awaiting_payment`. For each event, fetch the order with [`GET /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#get-an-order) and save it.
2. **Polling as a safety net.** Every so often (for example every quarter of an hour), run the [Incremental sync](https://docs.rephut.com/developers/incremental-sync) recipe with `updatedSince`. It catches anything a webhook missed, such as events from while your endpoint was down.
3. **One way to save.** Both paths save the order by `id` and overwrite your copy with what `GET` returned. Because the copy always comes from `GET`, order and duplicates don't matter.

## Handling an event

```js
// Called by your queue worker with the event body your receiver stored (see the Webhooks pages).
async function handleOrderEvent(event, saveOrder) {
  const response = await fetch(`https://api.rephut.com/v1/orders/${event.data.id}`, { headers: { Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}` } });
  if (response.status === 404) return; // The order is no longer yours.
  if (!response.ok) throw new Error(`HTTP ${response.status}`); // Let the queue retry later.
  const { data } = await response.json();
  await saveOrder(data);
}

export { handleOrderEvent };
```

## Things that trip people up

- Lists are sorted by creation time, so an old order that changed is on a later page. Always read every page of an `updatedSince` query.
- Watch your read limit (120 a minute). Fetching an order per event is one read; a busy store can batch events and fetch each order once.
- New orders created in the portal, from a file or by your store also send `order.status_changed`.

---

Source: https://docs.rephut.com/developers/guides/order-to-shipment

# From order to delivery

This guide follows one dropship order from your store to your buyer's door.

## 1. Make sure your products match

List [`GET /v1/products`](https://docs.rephut.com/developers/reference/products#list-your-products) and keep our `id` for each of your products. Map each of your SKUs once with [`POST /v1/sku-mappings`](https://docs.rephut.com/developers/reference/sku-mappings#map-your-sku-to-one-of-your-products); afterwards your order lines can carry just your SKU. Check stock with [`GET /v1/inventory`](https://docs.rephut.com/developers/reference/inventory#list-your-stock).

## 2. Check the order

Send the order to [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it). The preview tells you whether it would go straight to fulfilment (`willReserve`), which problems it has, which shipping options it can use and at what price, how much it would hold in your wallet and which products are short. Nothing is saved, so you can call it as often as you need.

## 3. Create it

Send the same body to [`POST /v1/orders`](https://docs.rephut.com/developers/reference/orders#create-an-order) with a new `Idempotency-Key`, stored with the order so that a retry reuses it ([Idempotency](https://docs.rephut.com/developers/idempotency)). Keep the returned `id`.

- If the order has no problems and all its stock is available, the stock is reserved and the estimated shipping and handling fee is held in your wallet ([Charges and your wallet](https://docs.rephut.com/developers/charges)). If some products are short, the order waits as `BACKORDERED` and the hold is placed once its stock is fully reserved.
- If it has problems, its status is `NEEDS_ATTENTION`. Fix it with [`PATCH /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#change-an-order-that-needs-attention), sending the whole order again, or cancel it with [`POST /v1/orders/{id}/cancel`](https://docs.rephut.com/developers/reference/orders#cancel-an-order-that-needs-attention).

## 4. Follow it

Subscribe to `order.status_changed` and `order.awaiting_payment` ([Webhook events](https://docs.rephut.com/developers/webhooks/events)) and fetch the order with [`GET /v1/orders/{id}`](https://docs.rephut.com/developers/reference/orders#get-an-order) when an event arrives.

- `BACKORDERED`: some products are short. `backorder` lists them and the purchase orders bringing them. With auto purchase on, those purchase orders are paid from your wallet automatically when the balance covers them.
- `RESERVED` with `payment` set (and `order.awaiting_payment`): the parcel is weighed but your balance was short. `payment` shows the amount due; top up in the portal.
- `WEIGHED`: the parcel is weighed and the fee charged.
- `SHIPPED`: `fulfilment.trackingNo` is set, and `trackingUrl` when the carrier has one. Pass them on to your buyer and your store.

## 5. When something goes wrong

- `409 order_not_editable`: the order has moved on and can't be changed through the API. Contact your account manager.
- `422 order_product_not_allowed`: a line points to a product that isn't yours.
- `409 store_order_no_taken`: you already have an order with that `storeOrderNo`. Look it up before creating another.
- A network error or timeout on create: send the same request again with the same `Idempotency-Key`.
- A saved `5xx` on create: list your orders and look for your `storeOrderNo` before you retry with a new key.

---

Source: https://docs.rephut.com/developers/guides/reliable-webhooks

# Handle webhooks reliably

Each event is sent until your endpoint accepts it or the retries run out (so you may receive an event more than once), in no particular order. A receiver built like this, together with the reconciliation in step 3, doesn't lose or double-count events.

## 1. Verify, store, answer

In the request handler, only:

1. read the raw body and verify the signature ([Verifying webhook signatures](https://docs.rephut.com/developers/webhooks/signatures));
2. store the event in a table or queue, keyed by its `id` (ignore it when the id is already there);
3. answer `200` straight away.

Do nothing slow in the handler. The time limit is 10 seconds, and slow answers turn into failed attempts and retries.

## 2. Process from the queue

A worker takes stored events one by one:

1. fetch the resource with its `GET` endpoint, using `data.id`;
2. save what `GET` returned;
3. mark the event as done.

Because you always act on the current state from `GET`, it doesn't matter that events arrive late, twice or out of order. If `GET` fails with a `5xx` or a network error, leave the event in the queue and try later.

## 3. Reconcile

Run a periodic catch-up with the API, such as [Incremental sync](https://docs.rephut.com/developers/incremental-sync) for orders. For purchase orders, shipments, requests and quotes, re-read the first page of the list to find new ones (lists are newest first by creation time and have no `updatedSince`), and `GET` the older ones you still consider open. It covers events from while your endpoint was turned off, which are not sent again.

## 4. Watch your endpoint

- Check **Recent deliveries** on the endpoint's page in the portal when something looks wrong.
- After 50 failed attempts in a row the endpoint is turned off and you get a notification. Turn it back on once it is fixed, then reconcile.
- Use **Send test event** after every deployment of your receiver.

## 5. Rotate secrets safely

Creating a new secret replaces the old one at once. Deploy the new secret right after creating it; attempts that fail in the meantime are retried with the new signature.

---

Source: https://docs.rephut.com/developers/changelog

# Changelog

## 2026-11-09: first release

The first public version of the API, `v1`.

- **Foundation:** API keys with permissions, created in the portal; rate limits per account; safe retries with `Idempotency-Key`; one response and error format with stable codes; a public OpenAPI document.
- **Reading:** account, wallet (balance, transactions, top-ups), products, inventory, orders (with `updatedSince` for incremental sync), purchase orders, shipments, sourcing and reorder requests, and quotes.
- **Writing:** check, create, change and cancel orders; map SKUs; estimate, request, cancel and confirm shipments; submit sourcing and reorder requests.
- **Webhooks:** events for orders, purchase orders, shipments, quotes and top-ups, with signed requests, retries, automatic turn-off and test events.

Not available yet, use the portal: paying from your wallet, accepting or declining quotes, and withdrawing requests.

---

Source: https://docs.rephut.com/developers/faq

# FAQ

### Is there a sandbox or test account?

No. The API works on your real account. To try things without saving anything, use [`POST /v1/orders/preview`](https://docs.rephut.com/developers/reference/orders#check-a-new-order-without-saving-it) and [`POST /v1/shipments/estimate`](https://docs.rephut.com/developers/reference/shipments#estimate-shipping-for-a-shipment-from-your-stock); reads never change anything.

### Can I call the API from a web page or a mobile app?

No. The API sends no CORS headers, and a key in a web page or app is visible to anyone. Call it from your server.

### I lost my key. Can I see it again?

No, keys are shown only once. Create a new key in **Settings → API access** and revoke the old one.

### My key stopped working. Why?

It was revoked, API access was turned off for your account (`403 api_not_enabled`), the portal user who created it was deactivated (`401 invalid_api_key`), or that user must change a temporary password (`403 account_action_required`). See [Authentication](https://docs.rephut.com/developers/authentication#why-a-key-is-refused).

### Are rate limits per key?

No, per account. All your keys share them. See [Rate limits](https://docs.rephut.com/developers/rate-limits).

### Does the API charge my wallet?

Creating orders doesn't charge it, but holds the estimated shipping and handling fee once the order's stock is fully reserved, and our warehouse charges the fee when it weighs the parcel. Purchase orders placed by auto purchase are paid from your wallet automatically when the balance covers them. See [Charges and your wallet](https://docs.rephut.com/developers/charges).

### Can I pay, accept quotes or withdraw requests through the API?

Not yet. Use the portal for payments, top-ups, accepting or declining quotes and withdrawing requests.

### Why did my sync return orders I already had?

The safety margin in [Incremental sync](https://docs.rephut.com/developers/incremental-sync) makes some orders come back. Match them on `id`.

### Which time zone are times in?

Times are UTC (ISO 8601 with `Z`). Fields that are only a date, such as `paidOn` and `neededBy`, are dates in China time (UTC+8).

### Why are there no images in responses?

Images are only available in the portal for now.

### I missed webhooks while my endpoint was down. Will you resend them?

Failed attempts are retried for a while ([Webhook delivery and retries](https://docs.rephut.com/developers/webhooks/delivery)). Events from while an endpoint was turned off are not resent; catch up with the API.

### Can I see the webhook signing secret again?

No. Create a new secret on the endpoint's page; it replaces the old one at once.

### How many keys and endpoints can I have?

Up to 10 active keys and 5 webhook endpoints per account.

### Who do I contact?

Your account manager. Quote the `X-Request-Id` of the request you are asking about.