Set up selling

These guides cover the commercial side of a tenant over the API, from the price a buyer sees to what happens after the order is placed. They are for developers and integrators wiring those rules into a storefront, an ERP sync or their own service, and every call goes through the API gateway with the same two headers.

Before you start

• A tenant and an API key with access to the apps a guide uses (create an API key; which scope covers which app).
• Apps per guide:
  • Pricing: Pricing
  • Purchase approvals: Procurement, Cost Centers, Customers, Orders
  • Shipping rates: Shipping
  • Confirming invoice payments: Payments, Orders
  • Promotions and vouchers: Promotions
  • Quotes: Quotes, Orders
  • Shipping, cancelling and returns: Orders, Inventories, Payments (and Promotions if orders use a promotion)
  • Product images and documents: Products and Storage
  • Modelling a catalog: Products
  • Categories from rules: Products
  • Buyer permissions: Customers (and Orders, whose order placement enforces the grants)
  • Test payments: Payments (and Orders to record the result)
  • Number ranges: Orders and Quotes
• Products in the catalog for the pricing and product-media guides, and a cart priced by it for promotions. Import a BMECAT catalog is one way to get products there. The other guides need no catalog products of their own.

The guides

In page order. Each says when to use it.

1. Set up B2B pricing — a standard price list, quantity ladders, contract prices for one buyer, a market in its own currency, a dry-run bulk change, and the resolve call a storefront asks on every page. Use it when buyers should see more than one price. Promotions reduce a cart that pricing has already priced.
2. Set up purchase approvals and cost-center budgets — buyer roles, cost centers with budgets and rollover, approval rules, and the submit call that turns a checkout into an order or a purchase request. Use it when someone must sign a cart off first.
3. Set up shipping rates and tax — fixed, free and weight-tiered methods, carriers and tracking links, the market settings behind thresholds and delivery windows, and the quote call with the tax a checkout must not guess. Use it when a checkout needs a shipping price. Booking the shipment itself is guide 7.
4. Confirm invoice payments from your ERP — record a settled invoice or prepayment as paid from the system that sees the money arrive, stop the dunning clock and mark the order paid. Use it when buyers pay by invoice or prepayment.
5. Run promotions and voucher codes — an automatic promotion with conditions and an effect, stacking rules, a batch of single-use codes, and the calls that count a code against the order that used it and credit it back. Use it when a checkout should apply offers or codes. Guide 7 covers releasing one when an order is cancelled or returned.
6. Turn an accepted quote into an order — request and price a quote, let the buyer accept all or part of it, place the order from the draft the acceptance returns, and write the order back to the quote. Use it when a price is negotiated before the order. Guide 7 starts where it ends.
7. Ship, cancel and return an order — ship in parts, cancel single lines, take a return, and do the stock, promotion and refund steps that Orders never does for you. Use it when your system runs an order after it is placed. The ERP side is Hand an order to the ERP.
8. Manage product images and documents — upload images and datasheets, register them as catalog assets, reference them from products, serve resized images and hand out private datasheets by signed link. Use it when a catalog needs pictures and documents; an import does not carry them.
9. Model a catalog with attributes, families and variants — decide which facts are attributes, which products share a family and where variants split, then build a worked example, read completeness and repair a catalog that was imported flat. Use it before a catalog import or migration.
10. Build categories from rules — preview what a rule matches before saving it, recompute in a loop until the answer says done, decide whether disabled products count, react to the nightly run and its event, and see how rule categories sit next to imported ones. Use it when a catalog is too large to file by hand.
11. Give buyer staff the right permissions — map a customer's org chart onto buyer roles, read a contact's effective grants, decide registrations, and keep the roles in step with purchase approvals. Use it when buyers at one company should not all be able to do the same things.
12. Connect a payment provider and take a test payment — see which methods and providers a tenant has, ask what a buyer may pay with, connect a provider in test mode, take, capture and refund a payment against an order reference, and know what a provider callback changes. Use it before a checkout depends on Payments.
13. Configure order and quote numbers per market — seed the default ranges, add one range per market for orders and quotes, point each market's setting at it, and know what a number promises about gaps, simultaneous orders and later changes. Use it when an ERP or accounting needs predictable document numbers.

Reference

• Markets and pricing — markets, channels, price lists, payment and shipping.
• Customers — the organizations and contacts that contract prices are scoped to.
• Orders — carts, orders and what happens after checkout.