Shops

A user can have one or more shops and be able to read or manage attached resources like shipments. A shipment is always associated with a shop.

Attributes

Attribute

Type

Required

Description

name

string

Name of the shop.

website

string

URL of the website of the shop.

return_address

address

The address a parcel is returned to when delivery fails.

sender_address

address

The address parcels for this shop are sent from.

reference

string

A reference for this shop, given by the user.

style

style

The style of the shop. Determines the colors of the branded tracking page.

logo_url

string

URL of the logo of the shop. Displayed on the branded tracking page.

created_at

integer

Unix timestamp when the shop was created.

Relationship

Type

Required

Description

organization

organizations

The organization the shop belongs to

Endpoints

GET /shops

Retrieving a list of shops.

Scope

Any of the following scopes:

  • organizations.manage

  • shipments.manage

Request

GET /shops HTTP/1.1
Accept: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/shops

Response

{
  "data": [
    {
      "type": "shops",
      "id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
      "attributes": {
        "name": "MyParcel.com",
        "return_address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "phone_number": "+31 234 567 890"
        },
        "sender_address": {
          "street_1": "Baker Street",
          "street_2": "Marylebone",
          "street_number": 221,
          "street_number_suffix": "B",
          "postal_code": "NW1 6XE",
          "city": "London",
          "country_code": "GB",
          "first_name": "Sherlock",
          "last_name": "Holmes",
          "company": "Holmes Investigations",
          "phone_number": "+31 234 567 890"
        },
        "website": "https://www.myparcel.com",
        "created_at": 1504801719,
        "reference": "MyParcel.com",
        "style": {
          "primary_color": "#008800",
          "secondary_color": "#202025",
          "background_color": "#fafafa",
          "foreground_color": "#ffffff",
          "accent_color": "ffba00",
        },
        "logo_url": "https://www.mywebsite.com/logo.png"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
          }
        }
      },
      "links": {
        "self": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
      }
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_records": 1
  },
  "links": {
    "self": "https://sandbox-api.myparcel.com/shops?page[number]=1&page[size]=30",
    "first": "https://sandbox-api.myparcel.com/shops?page[number]=1&page[size]=30",
    "last": "https://sandbox-api.myparcel.com/shops?page[number]=1&page[size]=30"
  }
}
GET /shops/{shop_id}

Retrieve a specific shop.

Scope

Any of the following scopes:

  • organizations.manage

  • shipments.manage

Request

GET /shops/{shop_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99

Response

{
  "data": {
    "type": "shops",
    "id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
    "attributes": {
      "name": "MyParcel.com",
      "return_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "phone_number": "+31 234 567 890"
      },
      "sender_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "phone_number": "+31 234 567 890"
      },
      "website": "https://www.myparcel.com",
      "created_at": 1504801719,
      "reference": "MyParcel.com",
      "style": {
          "primary_color": "#008800",
          "secondary_color": "#202025",
          "background_color": "#fafafa",
          "foreground_color": "#ffffff",
          "accent_color": "ffba00",
      },
      "logo_url": "https://www.mywebsite.com/logo.png"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
        }
      }
    },
    "links": {
      "self": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
    }
  }
}
POST /shops

Create a shop.

Scope

  • shops.manage

Request

POST /shops HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/shops

{
  "data": {
    "type": "shops",
    "attributes": {
      "name": "MyParcel.com",
      "return_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "phone_number": "+31 234 567 890"
      },
      "sender_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "phone_number": "+31 234 567 890"
      },
      "website": "https://www.myparcel.com",
      "reference": "MyParcel.com",
      "style": {
          "primary_color": "#008800",
          "secondary_color": "#202025",
          "background_color": "#fafafa",
          "foreground_color": "#ffffff",
          "accent_color": "ffba00",
      },
      "logo_url": "https://www.mywebsite.com/logo.png"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
        }
      }
    },
    "meta": {
      "logo": {
        "mime_type": "image/png",
        "contents": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
      }
    }
  }
}

Response

{
  "data": {
    "type": "shops",
    "id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
    "attributes": {
      "name": "MyParcel.com",
      "return_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "phone_number": "+31 234 567 890"
      },
      "sender_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "phone_number": "+31 234 567 890"
      },
      "website": "https://www.myparcel.com",
      "created_at": 1504801719,
      "reference": "MyParcel.com",
      "style": {
          "primary_color": "#008800",
          "secondary_color": "#202025",
          "background_color": "#fafafa",
          "foreground_color": "#ffffff",
          "accent_color": "ffba00",
      },
      "logo_url": "https://www.mywebsite.com/logo.png"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
        }
      }
    },
    "links": {
      "self": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
    }
  }
}
PATCH /shops/{shop_id}

Update an existing shop.

Scope

  • shops.manage

Request

In this example we’re changing the name of the shop to “Sherlock Holmes’ trinkets”

PATCH /shops/{shop_id} HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Example: https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99

{
  "data": {
    "type": "shops",
    "id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
    "attributes": {
      "name": "Sherlock Holmes' trinkets"
    }
  }
}

Response

{
  "data": {
    "type": "shops",
    "id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
    "attributes": {
      "name": "Sherlock Holmes' trinkets",
      "return_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "phone_number": "+31 234 567 890"
      },
      "sender_address": {
        "street_1": "Baker Street",
        "street_2": "Marylebone",
        "street_number": 221,
        "street_number_suffix": "B",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB",
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "company": "Holmes Investigations",
        "phone_number": "+31 234 567 890"
      },
      "website": "https://www.myparcel.com",
      "created_at": 1504801719,
      "reference": "MyParcel.com",
      "style": {
          "primary_color": "#008800",
          "secondary_color": "#202025",
          "background_color": "#fafafa",
          "foreground_color": "#ffffff",
          "accent_color": "ffba00",
      },
      "logo_url": "https://www.mywebsite.com/logo.png"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
        }
      }
    },
    "meta": {
      "logo": {
        "mime_type": "image/png",
        "contents": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
      }
    },
    "links": {
      "self": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
    }
  }
}