Merchant settings API

The merchant settings API allows you to query the current settings for your merchant account and to make updates to this via API. It also covers the operating hours of your store, which Shippit uses when it works out pickup and delivery windows.

Endpoints

GET/merchantRetrieve your merchant account settings
PATCH/merchantUpdate your merchant account settings
GET/merchants/settings/locations/operating_hoursRetrieve your store operating hours
PUT/merchants/settings/locations/operating_hoursReplace your store operating hours

The merchant object

store_namestringRequired: none
company_namestringOptional: none
contact_namestringRequired: none
contact_phonestringRequired: none
preparation_timestringRequired: The time in minutes to allow for an order to be prepared for carrier pickup
address_1stringRequired: none
suburbstringRequired: none
statestringRequired: none
postcodestringRequired: none
country_codestringRequired: none
website_urlstringOptional: The URL of the merchant website
webhook_urlstringOptional: URL to use for sending order status. Returns the earliest created webhook.
supports_landed_cost_quotingstringOptional: Whether the merchant supports landed cost quoting

Sample responseJSON

{
  "response": {
    "store_name": "Harolds Harpoons",
    "company_name": "Harold Pty Ltd",
    "contact_name": "Robert",
    "contact_phone": "0400000000",
    "shipping_cart_method_name": "",
    "preparation_time": 60,
    "website_url": "www.haroldsharpoons.com.au",
    "address_1": "110 Rex Road",
    "suburb": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country_code": "AU"
  }
}

The operating hours object

working_daysarray of objectsOptional

The operating hours of your store for each day of the week

Show child attributesHide child attributes

dayenumOptional: The day of the week in lowercase. Possible values are monday, tuesday, wednesday, thursday, friday, saturday, sunday.
beginning_of_workdaystringOptional: The start time of the workday in HH:MM format
end_of_workdaystringOptional: The end time of the workday in HH:MM format
is_openbooleanOptional: Whether the store is open on the given day. Use true for open, false for closed.

Sample responseJSON

{
  "working_days": [
    {
      "day": "monday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "tuesday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "wednesday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "thursday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "friday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "saturday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": false
    },
    {
      "day": "sunday",
      "beginning_of_workday": "00:00",
      "end_of_workday": "17:00",
      "is_open": false
    }
  ]
}

Retrieve merchant settings

GET/merchant

Returns an object representing your merchant account settings.

To perform this operation, you must be authenticated with an authentication token.

Response codes

Status	Meaning	Description
200	OK	Returns an object representing your merchant account settings.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

Response

JSON

{
  "response": {
    "store_name": "Harolds Harpoons",
    "company_name": "Harold Pty Ltd",
    "contact_name": "Robert",
    "contact_phone": "0400000000",
    "shipping_cart_method_name": "",
    "preparation_time": 60,
    "website_url": "www.haroldsharpoons.com.au",
    "address_1": "110 Rex Road",
    "suburb": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country_code": "AU"
  }
}

Update merchant settings

PATCH/merchant

Given an object with the desired settings to update, updates the Merchant settings on Shippit.

To perform this operation, you must be authenticated with an authentication token.

The updated merchant details are returned in full.

Parameters

Wrap the fields you want to change in a merchant object.

store_namestringOptional: none
company_namestringOptional: none
contact_namestringOptional: none
contact_phonestringOptional: none
preparation_timestringOptional: The time in minutes the store needs to prepare an order for carrier pickup
address_1stringOptional: none
suburbstringOptional: none
statestringOptional: none
postcodestringOptional: none
website_urlstringOptional: The URL of the merchant website
webhook_urlstringOptional: URL to use for sending order status

Response codes

Status	Meaning	Description
200	OK	The updated merchant account.
400	Bad Request	Returned when Shippit has a problem with the input parameters. Not all input errors can result in this error. Depending on the request, the error may be parsed as an unknown error or as part of the response body. If returned as text/html, it is blank.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
422	Unprocessable Entity	Returned when a submitted value fails validation, such as an address Shippit can't save.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

RequestJSON

{
  "merchant": {
    "store_name": "New Store Name"
  }
}

Response

JSON

{
  "response": {
    "store_name": "New Store Name",
    "company_name": "Harold Pty Ltd",
    "contact_name": "Robert",
    "contact_phone": "0400000000",
    "shipping_cart_method_name": "",
    "preparation_time": 60,
    "website_url": "www.haroldsharpoons.com.au",
    "address_1": "110 Rex Road",
    "suburb": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country_code": "AU"
  }
}

Retrieve operating hours

GET/merchants/settings/locations/operating_hours

Returns an object representing your merchant operating hours settings.

To perform this operation, you must authenticate with an authentication token.

Response codes

Status	Meaning	Description
200	OK	Returns an object representing the operating hours of your store for each day of the week.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

Response

JSON

{
  "working_days": [
    {
      "day": "monday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "tuesday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "wednesday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "thursday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "friday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "saturday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": false
    },
    {
      "day": "sunday",
      "beginning_of_workday": "00:00",
      "end_of_workday": "17:00",
      "is_open": false
    }
  ]
}

Update operating hours

PUT/merchants/settings/locations/operating_hours

Given an object with the desired settings to update, updates the merchant operating hours settings on Shippit.

To perform this operation, you must authenticate with an authentication token.

The updated operating hours are returned in full.

Parameters

working_daysarray of objectsbodyRequired

Provide all 7 working days in the working_days array.

Show child attributesHide child attributes

dayenumOptional: The day of the week in lowercase. Possible values are monday, tuesday, wednesday, thursday, friday, saturday, sunday.
beginning_of_workdaystringOptional: The start time of the workday in HH:MM format
end_of_workdaystringOptional: The end time of the workday in HH:MM format
is_openbooleanOptional: Whether the store is open on the given day. Use true for open, false for closed.

Response codes

Status	Meaning	Description
200	OK	The updated merchant operating hours
400	Bad Request	Returned when Shippit has a problem with the input parameters. Not all input errors result in this error. Depending on the request, the system may parse the error as an unknown error or include it in the response body. If returned as text or html, it's blank.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
500	Internal Server Error	Returned when Shippit can't save the operating hours, or when an unknown error occurs. Carries an `errors` array of strings rather than an error object.

RequestJSON

{
  "working_days": [
    {
        "day": "monday",
        "beginning_of_workday": "09:00",
        "end_of_workday": "17:00",
        "is_open": true
    },
    {
        "day": "tuesday",
        "beginning_of_workday": "09:00",
        "end_of_workday": "17:00",
        "is_open": true
    },
    {
        "day": "wednesday",
        "beginning_of_workday": "09:00",
        "end_of_workday": "17:00",
        "is_open": true
    },
    {
        "day": "thursday",
        "beginning_of_workday": "09:00",
        "end_of_workday": "17:00",
        "is_open": true
    },
    {
        "day": "friday",
        "beginning_of_workday": "09:00",
        "end_of_workday": "17:00",
        "is_open": true
    },
    {
        "day": "saturday",
        "beginning_of_workday": "09:00",
        "end_of_workday": "17:00",
        "is_open": false
    },
    {
        "day": "sunday",
        "beginning_of_workday": "00:00",
        "end_of_workday": "17:00",
        "is_open": false
    }
  ]
}

Response

JSON

{
  "working_days": [
    {
      "day": "monday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "tuesday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "wednesday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "thursday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "friday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": true
    },
    {
      "day": "saturday",
      "beginning_of_workday": "09:00",
      "end_of_workday": "17:00",
      "is_open": false
    },
    {
      "day": "sunday",
      "beginning_of_workday": "00:00",
      "end_of_workday": "17:00",
      "is_open": false
    }
  ]
}

The error object

errorstringRequired: Error code returned by Shippit
error_descriptionstringOptional: Human-readable description of the error