Guide 08 · Developer docs

Commerce

A Core dna store is a set of records and an API that moves a purchase from cart to order: products described in every language and priced in every currency the store sells in, a cart, a checkout that becomes an order, invoices, payments, tax and shipping. The site builds the storefront on top: the cart and checkout pages, their scripts, and the customer emails.

L2–L3
Unit 06 · Tax and shipping configuration

Making a shipping method appear at checkout

Tax and shipping configuration Page 25 of 31 Updated

What a shipping method needs before it offers a rate for a fulfilment, as a checklist in the order the platform applies it, with a quick test that tells the method's settings apart from its template.

Who this is for. Developers and administrators whose shipping method is missing from the rates at checkout. After this page you can find the step the method misses and put it right.

Seeing the rates

Work on a test checkout. Create shipping for it with the delivery address in question, and ask for the rates only (Creating shipping and showing the rates):

HTTP 
POST /cdna-api/checkout/<id>/shipping/simple-delivery?properties={ fulfillments { shippingRates { id, name, total } } }
Content-Type: application/json

{"countryName": "New Zealand", "addressLine1": "1 Queen Street", "postcode": "1010"}

Each method that passes every step below adds its rates to shippingRates. A method that stops at a step is left out of the list, and the call still succeeds. The steps are in the order the platform applies them: a method reaches a step only after passing the ones before it.

The checklist

  1. The method is Active. Only active methods are considered.
  2. The method carries every item's shipping category. An item's category is its product's (a variant's is its product's), or the Default shipping category when the product has none. The method's categories must include the category of every item in the fulfilment: a method that carries Parcel but not Oversize offers nothing for a fulfilment holding one oversize item, so give mixed orders a method that carries both. Give a new method its categories when you create it.
  3. For a pickup, the method serves the warehouse. A pickup fulfilment has a warehouse, which must be among the method's warehouses. A delivery skips this step.
  4. The template runs to the end. Code that stops with an error, such as a method called on an empty value (the delivery address on a pickup, say), creates no rates for that fulfilment, and the platform logs "There is an error in the template method". Guard every value that can be empty.
  5. The template creates a rate for this fulfilment. The template decides where the method ships and what it takes, by reading the delivery address and the items. Follow the code with this address and these items in mind: a branch for other countries, or for lighter parcels, creates nothing for this one (A complete two-country set-up).
  6. Each total is a number of zero or more. A total that is not a number, or is negative, creates no rate, and the platform logs "Incorrect value trying to create a rate". Pass totals as strings of digits, such as '9.95', and check any arithmetic that builds one. On a multi-currency store, check there is a price for the checkout's currency (Currencies and languages).

Once the rate appears, the shopper chooses it within its Lifetime, an hour by default; a shopper who comes back later creates shipping again (A rate lasts an hour).

Telling the settings from the template

To tell steps 1 to 3 from steps 4 to 6, give the method, for a moment and on a development site, a template that creates one rate for every fulfilment:

Template code Shipping method: Template code, for the test 
{$rates->create('0', 'Test')}
{{ rates.create('0', 'Test') }}

Create shipping again. If the Test rate appears, the method passes steps 1 to 3 and the cause is in its template: test each branch with an address and a weight that should reach it. If it does not appear, check the method's Active switch, its categories against every item's, and, for a pickup, its warehouses. Put the real template back afterwards.

A rate for goods that are not shipped

A checkout needs a selected shipping rate before it can be paid (What "ready for payment" requires). A store selling goods that are not shipped, such as downloads or tickets, gives them a category of their own and a method that carries it and creates a free rate for every fulfilment.

Go deeper
GuideShipping methods and their templates GuideAddresses and shipping at checkout GuideThe checkout and when it can be paid GuideTesting tax and shipping

Was this page helpful?

Your answer goes to the docs team.