# Workflow

The integration in order, from a new account to orders arriving.

## Step 1: Get your token and confirm your channel is ready

Contact [support](https://help.bobshop.co.za/) to have an API source
installed. Confirm two things with them:

1. **Which environment** the token is for. Build against Sandbox (QA) first.
2. **That your channel has a category rule.** Add one in Bob Sync, on your
   channel's Rules page. Without one, no product can become a listing. See
   [What makes a product go live](../4_What%20makes%20a%20product%20go%20live/README.md).

## Step 2: Send one product and confirm it lists

Send **one** product with [Create or update a product](../6_Products/product_upsert.md): a name, a description,
at least one image, and one variant with a price above zero and a quantity of
at least one.

A `200` means we stored the product, not that a listing exists. Check that the
listing appeared on Bob Shop before going further. If it did not, see [What makes a product go live](../4_What%20makes%20a%20product%20go%20live/README.md).

Store the `id` we return, per environment. Updates only need
`product_reference`, but a delete needs the `id`. An `id` from the other
environment does not exist and fails the request.

## Step 3: Send your catalogue

- A few products: loop over [Create or update a product](../6_Products/product_upsert.md).
- Many products: use [Bulk upload](../7_Bulk%20upload/README.md). Request an upload URL, upload a JSON array
  of products to it, queue it, and poll the status.

A bulk file is a set of changes, not a replacement catalogue. Products you
leave out are untouched.

## Step 4: Keep your catalogue up to date

Send a product again whenever it changes. We match on `product_reference`
within your channel, so the same reference updates the product rather than
creating a duplicate.

Send the product's **complete `variants` list** every time. The array replaces
the product's variants, so a variant you leave out is deleted.

To remove a listing, call [Delete a product](../6_Products/product_delete.md) with our `id`. Leaving a product
out of a later bulk file does not remove it.

## Step 5: Receive orders and reconcile your stock

Give us a **webhook delivery URL** and we POST each paid order to it.

**We do not reduce the quantity you sent us when an item sells.** If your next
update still carries the pre-sale quantity, the old number goes back onto the
listing and the item can oversell. So on each order webhook:

1. Read `webhook_payload.orderItems`. `tradersReference` is the `sku` you
   supplied; `quantity` is how many sold.
2. Reduce the stock in your own system.
3. Send us the new quantity for the affected variants with [Create or update a product](../6_Products/product_upsert.md).

The same order can arrive more than once. Key on `orderId` and ignore
duplicates. See [Webhooks](../8_Webhooks/README.md) for the payload and delivery details.