Shipping Profiles

Overview of the Shipping Profile resource and associated endpoints.

3 minute read

IMPORTANT

Sellers building integrations into Marketplacer should only use the current GraphQL-based Seller API, and not this (REST-based) API.

All future developments, including new features will be added to the the GraphQL-based Seller API only, more details on this API can be found here

Shipping Profiles are 1 of 3 entities that combine to define a Shipping Rule. Shipping Rules are used to determine what postage charge to apply to a purchase.

The table below describes these 3 entities in more detail.

Entity	Purpose	Created By
Shipping Rate	The cost (rate) that can be applied by the rule. You can define multiple rates.	Operators (Admins) or Sellers
Shipping Zone	A zone is made up of a list of Zip or Post codes that defines a geographic area.	Operators (Admins) or Sellers
Shipping Profile	Determined by the Operator only, a Shipping Profile will typically relate to the size, weight or delivery time slot for the purchased item, but can be “anything”. Shipping Profiles are defined on the Variant	Operators (Admins) only

If the Marketplacer instance that you are selling on is using Shipping Rules, (you may need to check with your Marketplacer operator to see if this is the case), then you can use the Seller API to apply an existing Shipping Profile either when creating or updating Variants.

Listing Shipping Profiles

The Shipping Profiles defined by the marketplace operator can be retrieved with the following endpoint.

Request

GET /api/v2/shipping_profiles

Response

Status: 200 OK

[
  {
    "shipping_profile": {
      "id": 1,
      "name": "Morning Delivery (8am-12pm)",
      "description": "",
      "created_at": "2021-01-05T14:54:04.250+11:00",
      "updated_at": "2021-01-05T14:54:04.250+11:00"
    }
  },
  {
    "shipping_profile": {
      "id": 2,
      "name": "Afternoon Delivery (1pm-5pm)",
      "description": "",
      "created_at": "2021-01-05T14:54:22.913+11:00",
      "updated_at": "2021-01-05T14:54:22.913+11:00"
    }
  },
  {
    "shipping_profile": {
      "id": 3,
      "name": "All-Day Delivery (8am-5pm)",
      "description": "",
      "created_at": "2021-01-06T13:06:05.000+11:00",
      "updated_at": "2021-01-06T13:06:05.000+11:00"
    }
  }
]

Retain the id of the shipping profile you want to use when creating and updating variants - see next section.

Creating and Updating Variants

To assign a shipping profile to a variant, simply add shipping_profile_id (along with a value) to the attributes collection when creating or updating a variant. A simplified example payload is shown below:

{
  "data": {
    "type": "variants",
    "attributes": {
      "count_on_hand": 5,
      "barcode": "9300601 123456",
      "shipping_profile_id": 2
    }
  }
}

For detailed documentation of creating and updating variants, please refer to the sections below:

Getting a Variants Shipping Profile

You can request variant information by using the variant endpoint as follows:

GET /api/v2/client/variants/1

This will return shipping profile under the relationships section:

{
  "links": {
    "self": "https://yourmarketplace.com/api/v2/client/variants/1"
  },
  "data": {
    "type": "variants",
    "id": "4533440",
    "relationships": {
      "shipping_profile": {
        "data": {
          "type": "shipping_profiles",
          "id": "1"
        }
      },
    }
  },
  "included": [ ]
}

You can opt to explicitly include the shipping profile as follows:

GET /api/v2/client/variants/1?include=shipping_profile

This will include further data for the shipping profile in the include section of the payload:

{
  "links": {
    "self": "https://yourmarketplace.com/api/v2/client/variants/1"
  },
  "data": {
    "type": "variants",
    "id": "4533440",
    "relationships": {
      "shipping_profile": {
        "data": {
          "type": "shipping_profiles",
          "id": "1"
        }
      },
    }
  },
  "included": [
    {
      "type": "shipping_profiles",
      "id": "1",
      "attributes": {
        "name": "Morning Delivery (8am-12pm)",
        "description": ""
      }
    }  
  ]
}

Note

You can append ?include=shipping_profile when creating and updating variants (POST & PUT requests) which will return a similar shaped payload to that of the GET request.