REST API: Cart Shipping Rates

[mikejolley]

Takes a shipping address and returns a list of available shipping rates for the current cart.

GET /cart/shipping-rates

The shipping address schema can be borrowed from the core REST API, and includes the following:

'properties'  => array(
     'first_name' => array(
          'description' => __( 'First name.', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
     'last_name'  => array(
          'description' => __( 'Last name.', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
     'company'    => array(
          'description' => __( 'Company name.', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
     'address_1'  => array(
          'description' => __( 'Address line 1', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
     'address_2'  => array(
          'description' => __( 'Address line 2', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
     'city'       => array(
          'description' => __( 'City name.', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
     'state'      => array(
          'description' => __( 'ISO code or name of the state, province or district.', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
     'postcode'   => array(
          'description' => __( 'Postal code.', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
     'country'    => array(
          'description' => __( 'ISO code of the country.', 'woocommerce-rest-api' ),
          'type'        => 'string',
          'context'     => array( 'view', 'edit' ),
     ),
),

Also for reference, core shipping rates contain this data:

    protected $data = array(
        'id'          => '',
        'method_id'   => '',
        'instance_id' => 0,
        'label'       => '',
        'cost'        => 0,
        'taxes'       => array(),
    );

Example:

GET /cart/shipping-rates?country=US&postcode=90210&city

Response:

{
  "shipping_rates": [
    {
      "id": 1,
      "name": "Domestic Shipping",
      "description": "Shipping within the US using Fedex.",
      "price": "8.00",
      "handling_time": "3-5 days",
      "source": "shipping-extension-id"
    }
  ]
}

I'm thinking this naming will make more sense in an API. Essentially, source is the shipping method ID, and id is the shipping method instance ID used internally.

Questions:

• Do we need to include taxes like core does or is there a better way to calculate/surface this data? Does price include or exclude taxes?
• Handling time is not something included in core; how do we expose this to users/developers?

Tasks:

• [ ] Implement schema/endpoint
• [ ] Hook to allow address validation, w/ error response
• [ ] Cart->package (see core cart class)
• [ ] Get quotes, w/ caching if possible, from shipping extensions.
• [ ] Allow for handling_time field which doesn't exist in core but could be supported/added separately.

[issue-label-bot[bot]]

Issue Label Bot is not confident enough to auto-label this issue. See dashboard for more details.

[haszari]

Essentially, source is the shipping method ID, and id is the shipping method instance ID used internally.

Would it be clearer to name this field source => method to match the name in the UI, Shipping method ?

[haszari]

Do we need to include taxes like core does or is there a better way to calculate/surface this data? Does price include or exclude taxes?

Good question – I'm not familiar with how taxes apply to shipping, I'm guessing that's complex and subtle. What does the design call for?

Handling time is not something included in core; how do we expose this to users/developers?

This feels like an extra feature in the new cart layout – one option would be that we add this later as an enhancement (either in this cycle or later). Is there any existing support for handling time / shipping ETA estimate in core, or are we building this brand new for the optimised checkout/block UX?

I see it's in the existing mockups, how important is handling time/shipping ETA for v1 @garymurray @pmcpinto ?

[pmcpinto]

This feels like an extra feature in the new cart layout – one option would be that we add this later as an enhancement (either in this cycle or later). Is there any existing support for handling time / shipping ETA estimate in core, or are we building this brand new for the optimised checkout/block UX? I see it's in the existing mockups, how important is handling time/shipping ETA for v1 @garymurray @pmcpinto ?

Shipping time seems to be more a nice to have and if it doesn't exist in core it's better to backlog it and see if we have time to tackle this at the end of the cycle or in the upcoming one.

Do we need to include taxes like core does or is there a better way to calculate/surface this data? Does price include or exclude taxes?

I think that it will be better to stick with the behavior on core.

@garymurray what do you think about both questions?

[garymurray]

Shipping times

This was a recommended item via Baymard - so it would be nice to include, but is not a critical feature for v1 - it can be backlogged.

Taxes Do we need to include taxes like core does or is there a better way to calculate/surface this data? Does price include or exclude taxes?

Just to check you are referring to when their is an additional line item in the cart called Taxes here? I think for now we can just create an additional line item for this in the cart totals - like this:

[mikejolley]

Just to check you are referring to when their is an additional line item in the cart called Taxes here? I think for now we can just create an additional line item for this in the cart totals - like this:

Thinking about the API not the design; it comes down to when the tax calculations need to occur. Are the taxes returned from the shipping endpoint, or are the taxes calculated later when putting together the final total.

Shipping time seems to be more a nice to have and if it doesn't exist in core it's better to backlog it and see if we have time to tackle this at the end of the cycle or in the upcoming one.

I think it's best to allow for it in the API. Implementing it would require changes to the core shipping methods, so there will be no movement unless supported, somewhere.

[garymurray]

Thinking about the API not the design; it comes down to when the tax calculations need to occur. Are the taxes returned from the shipping endpoint, or are the taxes calculated later when putting together the final total.

How is this handled by Core currently - afaik the taxes are based on an entered/captured location - so it requires someone to have added or confirmed their location?

I think it's best to allow for it in the API. Implementing it would require changes to the core shipping methods, so there will be no movement unless supported, somewhere.

👍