# Create Address
Source: https://developers.artport.co/guide/api/addresses/create
### Overview
This endpoint can be used to create a new address.
Endpoint: `/api/v1/addresses`
Method: `POST`
It is critically important that you [verify the address](/guide/api/addresses/verify) before creating it.
Failure to verify the address may result in loss or delayed shipments.
You may also be **charged** should address correction be necessary by the carrier.
### Request
For example, "John Smith" or "Acme Products".
Minimum character length: `2`
Maximum character length: `50`
The contact email address.
Carriers may send one or more shipment tracking notifications to this email address.
Minimum character length: `6`
Maximum character length: `100`
The contact phone number.
This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).
Minimum character length: `7`
Maximum character length: `30`
Line 1 of the address.
Minimum character length: `2`
Maximum character length: `35`
Line 2 of the address.
Minimum character length: `2`
Maximum character length: `35`
The address' town or city.
Minimum character length: `2`
Maximum character length: `35`
The address' state, province, or region.
Minimum character length: `2`
Maximum character length: `30`
The address' post code.
Minimum character length: `2`
Maximum character length: `16`
A [Country](/guide/enums/countries) enum representing the address' country.
### Response
If the address is successfully created, the API will return a `201 Created` status code.
The response will contain the following content:
The ID of the newly created address.
```json Example Request Body Structure theme={"system"}
{
"name": "Kohler Group",
"email": "parisian.kristoffer@yahoo.com",
"phone": "+12069536978",
"line_1": "193 Dach Shores Suite 632",
"line_2": "Apt. 300",
"city": "Moenburgh",
"region": "Colorado",
"post_code": "72099",
"country": 1,
}
```
```json 201 theme={"system"}
{
"id": 10012
}
```
# Delete Address
Source: https://developers.artport.co/guide/api/addresses/delete
export const action_0 = "delete"
### Overview
This endpoint can be used to delete an address.
Endpoint: `/api/v1/addresses/{address_id}`
Method: `DELETE`
### URL Parameters
The ID of the address you wish to { action_0 }.
### Response
If the address is successfully deleted, the API will return a `204 No Content` status code.
The response will not contain any content.
```text 204 theme={"system"}
No Content
```
# List Addresses
Source: https://developers.artport.co/guide/api/addresses/list
### Overview
This endpoint can be used to retrieve a list of addresses.
Endpoint: `/api/v1/addresses/`
Method: `GET`
This endpoint returns a [paginated response](/guide/concepts/pagination).
### Response
If the addresses are successfully retrieved, the API will return a `200 OK` status code.
The response will contain the following content:
An array of [Address](/guide/schemas/address) objects.
If no addresses are found, the `data` field will be an empty array.
URLs for the first, last, previous, and next pages.
Explained in further detail in the [pagination](/guide/concepts/pagination) guide.
Metadata about the current page.
Explained in further detail in the [pagination](/guide/concepts/pagination) guide.
```json 200 theme={"system"}
{
"data": [
{
"id": 1,
"name": "Kohler Group",
"email": "parisian.kristoffer@yahoo.com",
"phone": "+12069536978",
"line_1": "193 Dach Shores Suite 632",
"line_2": "Apt. 300",
"city": "Moenburgh",
"region": "Colorado",
"post_code": "72099",
"country": 1,
"created_at": "2024-12-09 22:49:57",
"updated_at": "2024-12-09 22:49:57"
},
// Additional addresses...
],
"links": {
"first": "https://app.artport.co/api/v1/addresses?page=1",
"last": null,
"prev": null,
"next": "https://app.artport.co/api/v1/addresses?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://app.artport.co/api/v1/addresses",
"per_page": 20,
"to": 20
}
}
```
# Get Address
Source: https://developers.artport.co/guide/api/addresses/show
export const action_0 = "retrieve"
### Overview
This endpoint can be used to get a single address.
Endpoint: `/api/v1/addresses/{address_id}`
Method: `GET`
### URL Parameters
The ID of the address you wish to { action_0 }.
### Response
If the address is successfully retrieved, the API will return a `200 OK` status code.
The response will contain the following content:
An array containing a single [Address](/guide/schemas/address) object.
```json 200 theme={"system"}
{
"data": {
"id": 1,
"name": "Kohler Group",
"email": "parisian.kristoffer@yahoo.com",
"phone": "+12069536978",
"line_1": "193 Dach Shores Suite 632",
"line_2": "Apt. 300",
"city": "Moenburgh",
"region": "Colorado",
"post_code": "72099",
"country": 1,
"created_at": "2024-12-09 22:49:57",
"updated_at": "2024-12-09 22:49:57"
}
}
```
# Update Address
Source: https://developers.artport.co/guide/api/addresses/update
export const action_0 = "update"
### Overview
This endpoint can be used to update an address.
Endpoint: `/api/v1/addresses/{address_id}`
Method: `PATCH`
It is critically important that you [verify the address](/guide/api/addresses/verify) before updating it.
Failure to verify the address may result in loss or delayed shipments.
You may also be **charged** should address correction be necessary by the carrier.
### URL Parameters
The ID of the address you wish to { action_0 }.
### Request
For example, "John Smith" or "Acme Products".
Minimum character length: `2`
Maximum character length: `50`
The contact email address.
Carriers may send one or more shipment tracking notifications to this email address.
Minimum character length: `6`
Maximum character length: `100`
The contact phone number.
This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).
Minimum character length: `7`
Maximum character length: `30`
Line 1 of the address.
Minimum character length: `2`
Maximum character length: `35`
Line 2 of the address.
Minimum character length: `2`
Maximum character length: `35`
The address' town or city.
Minimum character length: `2`
Maximum character length: `35`
The address' state, province, or region.
Minimum character length: `2`
Maximum character length: `30`
The address' post code.
Minimum character length: `2`
Maximum character length: `16`
A [Country](/guide/enums/countries) enum representing the address' country.
### Response
If the address is successfully updated, the API will return a `204 No Content` status code.
The response will not contain any content.
```json Example Request Body Structure theme={"system"}
{
"name": "Kohler Group",
"email": "parisian.kristoffer@yahoo.com",
"phone": "+12069536978",
"line_1": "193 Dach Shores Suite 632",
"line_2": "Apt. 300",
"city": "Moenburgh",
"region": "Colorado",
"post_code": "72099",
"country": 1,
}
```
```text 204 theme={"system"}
No Content
```
# Verify Address
Source: https://developers.artport.co/guide/api/addresses/verify
### Overview
This endpoint can be used to verify an address.
Endpoint: `/api/v1/addresses/verify`
Method: `POST`
### Request
For example, "John Smith" or "Acme Products".
Minimum character length: `2`
Maximum character length: `50`
The contact email address.
Carriers may send one or more shipment tracking notifications to this email address.
Minimum character length: `6`
Maximum character length: `100`
The contact phone number.
This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).
Minimum character length: `7`
Maximum character length: `30`
Line 1 of the address.
Minimum character length: `2`
Maximum character length: `35`
Line 2 of the address.
Minimum character length: `2`
Maximum character length: `35`
The address' town or city.
Minimum character length: `2`
Maximum character length: `35`
The address' state, province, or region.
Minimum character length: `2`
Maximum character length: `30`
The address' post code.
Minimum character length: `2`
Maximum character length: `16`
A [Country](/guide/enums/countries) enum representing the address' country.
### Response
If the address is valid, the API will return a `200 OK` status code.
The response will not contain any content.
If the address is not valid, the API will return a `400 Bad Request` status code.
The response will contain the following content:
The name that was provided in the request.
The email address that was provided in the request.
The phone number that was provided in the request.
Line 1 of the address.
If the corresponding request field is not valid, then this may be set to a recommended alternative.
Line 2 of the address.
If the corresponding request field is not valid, then this may be set to a recommended alternative.
The address' town or city.
If the corresponding request field is not valid, then this may be set to a recommended alternative.
The address' state, province, or region.
If the corresponding request field is not valid, then this may be set to a recommended alternative.
The address' post code.
If the corresponding request field is not valid, then this may be set to a recommended alternative.
A [Country](/guide/enums/countries) enum representing the address' country that was provided in the request.
Whether the returned / revised address is recommended.
An [Address Verification Status](/guide/enums/address-verification-status) enum representing the status of the address verification.
A message which provides more information about the address verification status.
```json Example Request Body Structure theme={"system"}
{
"name": "Kohler Group",
"email": "artport.example@example.com",
"phone": "+123456789",
"line_1": "123 Example Street",
"line_2": "Apt. 456",
"city": "Moenburgh",
"region": "Colorado",
"post_code": "72099",
"country": 1,
}
```
```text 200 theme={"system"}
No Content
```
```json 400 theme={"system"}
{
"name": "Kohler Group",
"email": "artport.example@example.com",
"phone": "+123456789",
"line_1": "Revised line 1",
"line_2": "Revised line 2",
"city": "Revised city",
"region": "Revised region",
"post_code": "Revised post code",
"country": 1,
"recommended": true,
"status": 3,
"message": "The address was not found, but a similar one exists. Accept it or adjust if needed."
}
```
# Create Checkout Session
Source: https://developers.artport.co/guide/api/checkout/create
### Overview
This endpoint can be used to create a checkout session for a list of shipments.
Endpoint: `/api/v1/checkout`
Method: `GET`
A maximum of 10 shipments can be included in a single checkout session.
It is critical that you [verify the fulfillment and destination addresses](/guide/api/addresses/verify) for each shipment.
Failure to verify the addresses may result in loss or delayed shipments.
You may also be **charged** should address correction be necessary by the carrier.
Your organization requires a stored payment method in order to process a checkout session.
### Request
An array of up to `10` shipment IDs to be included in the checkout session.
The ID of the shipment to include in the checkout session.
### Response (200)
If the checkout session was successfully created, the API will return a `200 OK` status code.
The response will contain the following content:
An array of integers showing the price of each shipment included in the checkout session.
Each shipment ID is mapped to its price. For example, `125: 4500` means that a shipment with ID `125` has a price of `4500`.
Prices are displayed in U.S. cents. For example, a price of `4500` is equal to `4500` cents (`$45.00` U.S. dollars).
The total price of all shipments included in the checkout session.
The total is displayed in U.S. cents. For example, a total of `17500` is equal to `17500` cents (`$175.00` U.S. dollars).
### Response (500)
If the checkout session was not successfully created, the API will return a `500 Server Error` status code.
The response will contain the following content:
A [Checkout Session Status](/guide/enums/checkout-session-status) enum representing the status of the checkout session.
A human-readable message explaining the error.
```json Example Request Body Structure theme={"system"}
{
"shipments": [
125,
126,
127
]
}
```
```json 200 theme={"system"}
{
"shipments": [
125: 4500,
126: 6000,
127: 7000,
],
"total": 17500
}
```
```json 500 theme={"system"}
{
"status": 0,
"message": "Sorry, we're receiving a lot of requests... try again in a minute"
}
```
# Finalize Checkout Session
Source: https://developers.artport.co/guide/api/checkout/store
### Overview
This endpoint can be used to finalize a checkout session and pay for the shipments.
Endpoint: `/api/v1/checkout`
Method: `POST`
A maximum of 10 shipments can be included in a single checkout session.
You must first use the `GET` endpoint so that the price may be calculated for each shipment. If you attempt to finalize a shipment that does not have a price, then you will receive an error.
This endpoint will charge the total price of each shipment in the checkout session to the organization's payment method.
Please ensure that each shipment's details are correct, and that all [addresses have been verified](/guide/api/addresses/verify) before finalising the checkout session.
Failure to do so may result in delays, lost shipments, or extra charges.
Your organization requires a stored payment method in order to process a checkout session.
### Request
An array of up to `10` shipment IDs to be included in the finalized checkout session.
The ID of the shipment to finalize in the checkout session.
### Response (204)
If the checkout session is successfully stored, the API will return a `204 No Content` status code.
The response will not contain any content.
### Response (403)
If the organization does not have a valid payment method to charge, then the API will return a `403 Forbidden` status code.
### Response (402)
If the checkout session was not successfully stored because the payment provider declined the organization's card, then the API will return a `402 Payment Required` status code.
Receiving this response will automatically invalidate your payment method. You will need to address this via the ArtPort website before you can make further payment attempts.
The response will contain the following content:
The internal status code of the error.
A human-readable message explaining the error.
### Response (409)
If the checkout session was not successfully created because payment failed, then the API will return a `409 Conflict` status code.
In most cases, this is a temporary error and you can simply retry the request. It is recommended that you wait a minute or so before retrying. This increases the chance that your request will be processed successfully.
The response will contain the following content:
The internal status code of the error.
A human-readable message explaining the error.
```json Example Request Body Structure theme={"system"}
{
"shipments": [
125,
126,
127
]
}
```
```text 204 theme={"system"}
No Content
```
```json 403 theme={"system"}
"You are not able to do this"
```
```json 402 theme={"system"}
{
"status": 0,
"message": "Your card was declined... check your wallet"
}
```
```json 409 theme={"system"}
{
"status": 1,
"message": "Something went wrong... please try again"
}
```
# Show Condition Report
Source: https://developers.artport.co/guide/api/condition-reports/show
### Overview
This endpoint can be used to retrieve the condition report for a given shipment.
Endpoint: `/api/v1/reports/{shipment_id}`
Method: `GET`
### URL Parameters
The ID of the shipment to retrieve the condition report for.
### Response (200)
If the condition report is successfully retrieved, the API will return a `200 OK` status code.
The response will contain the following content:
A URL to a ZIP file containing the condition report images.
The URL is a temporary, signed URL which will expire 1 week after being generated.
### Response (403)
If the condition report was not successfully retrieved (because it does not exist), the API will return a `403 Forbidden` status code.
The response will not contain any content.
```json 200 theme={"system"}
{
"images": "https://app.artport.co/temporary-url-to-zip-file"
}
```
# Store Condition Report
Source: https://developers.artport.co/guide/api/condition-reports/store
### Overview
This endpoint can be used to store the condition report for a given shipment.
Endpoint: `/api/v1/reports/{shipment_id}/{set}`
Method: `POST`
A shipment's condition report is made up of two "sets".
Set `1` contains the photos of the shipment (artwork and box) before it is shipped.
Set `2` contains the photos of the shipment (artwork and box) after it is received.
### Requirements
In order to submit `Set 1`, the [shipment's status](/guide/enums/shipment-status) must be `Delivered`, and the submission must be made within `30 days` of the shipment's arrival at the fulfillment address.
In order to submit `Set 2`, the [shipment's status](/guide/enums/shipment-status) must be `Arrived`, and the submission must be made within `24 hours` of the shipment's arrival at the destination address.
### URL Parameters
The ID of the shipment.
The set being uploaded. This can be either `1` or `2`.
### Request
Since the request requires that photos (binary files) are included, you will need to ensure that the request is sent using `multipart/form-data`.
An array of photos that document the condition of the shipment's box.
Required number of photos: `6`.
Maximum file size for each photo: `1MB`.
Permitted file types for the photo: `JPG, PNG`.
The photos should be ordered within the array like so:
* Front surface
* Back surface
* Top surface
* Bottom surface
* Left surface
* Right surface
An array of photos that document the condition of the shipment's artwork.
Required number of photos: `6`.
Maximum file size for each photo: `1MB`.
Permitted file types for the photo: `JPG, PNG`.
The photos should be ordered within the array like so:
* Front surface
* Back surface
* Top surface
* Bottom surface
* Left surface
* Right surface
```shell Example Request (cURL) theme={"system"}
curl -X POST https://artport.co/api/v1/reports/1/1 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "box[]=@/path/to/box_1.jpg" \
-F "box[]=@/path/to/box_2.jpg" \
-F "box[]=@/path/to/box_3.jpg" \
-F "box[]=@/path/to/box_4.jpg" \
-F "box[]=@/path/to/box_5.jpg" \
-F "box[]=@/path/to/box_6.jpg" \
-F "art[]=@/path/to/art_1.jpg" \
-F "art[]=@/path/to/art_2.jpg" \
-F "art[]=@/path/to/art_3.jpg" \
-F "art[]=@/path/to/art_4.jpg" \
-F "art[]=@/path/to/art_5.jpg" \
-F "art[]=@/path/to/art_6.jpg"
```
```js Example Request (JS / Node) theme={"system"}
const fs = require('fs');
const FormData = require('form-data');
const formData = new FormData();
formData.append('box[]', fs.createReadStream('images/box_1.jpg'));
formData.append('box[]', fs.createReadStream('images/box_2.jpg'));
formData.append('box[]', fs.createReadStream('images/box_3.jpg'));
formData.append('box[]', fs.createReadStream('images/box_4.jpg'));
formData.append('box[]', fs.createReadStream('images/box_5.jpg'));
formData.append('box[]', fs.createReadStream('images/box_6.jpg'));
formData.append('art[]', fs.createReadStream('images/art_1.jpg'));
formData.append('art[]', fs.createReadStream('images/art_2.jpg'));
formData.append('art[]', fs.createReadStream('images/art_3.jpg'));
formData.append('art[]', fs.createReadStream('images/art_4.jpg'));
formData.append('art[]', fs.createReadStream('images/art_5.jpg'));
formData.append('art[]', fs.createReadStream('images/art_6.jpg'));
fetch('https://artport.co/api/v1/reports/1/1', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
...formData.getHeaders()
},
body: formData
})
.then(response => {
if (response.status === 201) {
console.log('Upload successful! No content returned.');
} else {
throw new Error(`Unexpected response status: ${response.status}`);
}
})
.catch(error => console.error('Upload failed:', error));
```
### Response
If the condition report is successfully stored, the API will return a `201 Created` status code.
The response will not contain any content.
```text 201 theme={"system"}
No content
```
# Create Shipment
Source: https://developers.artport.co/guide/api/shipments/create
### Overview
This endpoint can be used to create new shipments.
A maximum of 10 shipments can be created in a single request.
Endpoint: `/api/v1/shipments`
Method: `POST`
It is critical that you [verify the fulfillment and destination addresses](/guide/api/addresses/verify) before using them.
Failure to verify the addresses may result in loss or delayed shipments.
You may also be **charged** should address correction be necessary by the carrier.
### Request
When creating a shipment, you can use either of the following two approaches to specify the fulfillment and destination addresses:
* Use the `fulfillment_address_id` and `destination_address_id` fields to reference existing addresses that have already been stored on ArtPort.
* Provide the address details directly in the `fulfillment_address` and `destination_address` fields.
You can also combine these approaches. For example, by using a `fulfillment_address_id` and a `destination_address`, or vice versa.
For examples of how to use these fields, see the request examples on this page.
Array of shipment objects to be created.
Minimum objects in the array: `1`
Maximum objects in the array: `10`
Each shipment object must consist of the following fields:
The name or a brief description of the piece. You can also use an internal reference number.
Minimum character length: `2`
Maximum character length: `50`
The value of the artwork in USD \$.
Always use an accurate value to make sure that any insurance claims are properly honored.
Minimum value: `50`
Maximum value: `10000`
The length of the piece in inches.
Minimum length: `17`
Maximum length: `44`
The height of the piece in inches.
Minimum height: `13`
Maximum height: `34`
The depth of the piece in inches.
Minimum depth: `1`
Maximum depth: `4`
A [Service](/guide/enums/services) enum representing the service to be used for the shipment.
The ID of an existing address to be used as the fulfillment address.
This field is required if the `fulfillment_address` field is not provided.
An object containing the fulfillment address details.
This field is required if the `fulfillment_address_id` field is not provided.
For example, "John Smith" or "Acme Products".
Minimum character length: `2`
Maximum character length: `50`
The contact email address.
Carriers may send one or more shipment tracking notifications to this email address.
Minimum character length: `6`
Maximum character length: `100`
The contact phone number.
This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).
Minimum character length: `7`
Maximum character length: `30`
Line 1 of the address.
Minimum character length: `2`
Maximum character length: `35`
Line 2 of the address.
Minimum character length: `2`
Maximum character length: `35`
The address' town or city.
Minimum character length: `2`
Maximum character length: `35`
The address' state, province, or region.
Minimum character length: `2`
Maximum character length: `30`
The address' post code.
Minimum character length: `2`
Maximum character length: `16`
A [Country](/guide/enums/countries) enum representing the address' country.
The ID of an existing address to be used as the destination address.
This field is required if the `destination_address` field is not provided.
An object containing the destination address details.
This field is required if the `destination_address_id` field is not provided.
For example, "John Smith" or "Acme Products".
Minimum character length: `2`
Maximum character length: `50`
The contact email address.
Carriers may send one or more shipment tracking notifications to this email address.
Minimum character length: `6`
Maximum character length: `100`
The contact phone number.
This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).
Minimum character length: `7`
Maximum character length: `30`
Line 1 of the address.
Minimum character length: `2`
Maximum character length: `35`
Line 2 of the address.
Minimum character length: `2`
Maximum character length: `35`
The address' town or city.
Minimum character length: `2`
Maximum character length: `35`
The address' state, province, or region.
Minimum character length: `2`
Maximum character length: `30`
The address' post code.
Minimum character length: `2`
Maximum character length: `16`
A [Country](/guide/enums/countries) enum representing the address' country.
### Response
If the shipments are successfully created, the API will return a `201 Created` status code.
The response will contain the following content:
Details of the newly created shipments.
The ID of the newly created shipment.
The title of the newly created shipment.
```json Request (with address IDs) theme={"system"}
{
"shipments": [
{
"title": "Test Shipment",
"value": 1000,
"length": 17,
"height": 13,
"depth": 1,
"service": 1,
"fulfillment_address_id": 123,
"destination_address_id": 456,
},
// Additional shipments to be created...
]
}
```
```json Request (with address details) theme={"system"}
{
"shipments": [
{
"title": "Test Shipment",
"value": 1000,
"length": 17,
"height": 13,
"depth": 1,
"service": 1,
"fulfillment_address": {
"name": "Schaefer, Nolan and Wehner",
"email": "dave45@gmail.com",
"phone": "+12069536978",
"line_1": "492 Quitzon Avenue Apt. 157",
"line_2": "Apt. 027",
"city": "Gustside",
"region": "Massachusetts",
"post_code": "17594-7013",
"country": 1
},
"destination_address": {
"name": "Krajcik, Kuhn and Eichmann",
"email": "teresa93@gmail.com",
"phone": "+12069536978",
"line_1": "1712 Marina Ramp Suite 512",
"line_2": "Apt. 235",
"city": "Port Marlon",
"region": "Indiana",
"post_code": "62893",
"country": 1
}
},
// Additional shipments to be created...
]
}
```
```json Request (mixed) theme={"system"}
{
"shipments": [
{
"title": "Test Shipment",
"value": 1000,
"length": 17,
"height": 13,
"depth": 1,
"service": 1,
"fulfillment_address_id": 123,
"destination_address": {
"name": "Krajcik, Kuhn and Eichmann",
"email": "teresa93@gmail.com",
"phone": "+12069536978",
"line_1": "1712 Marina Ramp Suite 512",
"line_2": "Apt. 235",
"city": "Port Marlon",
"region": "Indiana",
"post_code": "62893",
"country": 1
}
},
// Additional shipments to be created...
]
}
```
```json 201 theme={"system"}
{
"shipments": [
{
"id": 10011,
"title": "Shipment 1",
},
{
"id": 10012,
"title": "Shipment 2",
}
]
}
```
# Delete Shipment
Source: https://developers.artport.co/guide/api/shipments/delete
export const action_0 = "delete"
### Overview
This endpoint can be used to delete a shipment.
Endpoint: `/api/v1/shipments/{shipment_id}`
Method: `DELETE`
### URL Parameters
The ID of the shipment you wish to { action_0 }.
### Response
If the shipment is successfully deleted, the API will return a `204 No Content` status code.
The response will not contain any content.
```text 204 theme={"system"}
No Content
```
# List Shipments
Source: https://developers.artport.co/guide/api/shipments/list
### Overview
This endpoint can be used to retrieve a list of shipments.
Endpoint: `/api/v1/shipments`
Method: `GET`
This endpoint returns a [paginated response](/guide/concepts/pagination).
### Response
If the shipments are successfully retrieved, the API will return a `200 OK` status code.
The response will contain the following content:
An array of [Shipment](/guide/schemas/shipment) objects.
If no shipments are found, the `data` field will be an empty array.
URLs for the first, last, previous, and next pages.
Explained in further detail in the [pagination](/guide/concepts/pagination) guide.
Metadata about the current page.
Explained in further detail in the [pagination](/guide/concepts/pagination) guide.
```json 200 theme={"system"}
{
"data": [
{
"id": 1,
"title": "Secured local capability",
"value": 7431,
"status": 2,
"box": 2,
"length": 37,
"height": 21,
"depth": 1,
"service": 1,
"fulfillment_address": {
"id": 2,
"name": "Gaylord-Ratke",
"email": "warren25@hotmail.com",
"phone": "+12069536978",
"line_1": "684 Kiley Cape",
"line_2": "Suite 269",
"city": "Bednarburgh",
"region": "Idaho",
"post_code": "29709",
"country": 1,
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
},
"destination_address": {
"id": 3,
"name": "Weissnat-Larkin",
"email": "weimann.aylin@gmail.com",
"phone": "+12069536978",
"line_1": "141 Chaim Mountains",
"line_2": "Apt. 556",
"city": "Lake Kamron",
"region": "South Dakota",
"post_code": "43650-3558",
"country": 1,
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
},
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
},
// Additional shipments...
],
"links": {
"first": "https://app.artport.co/api/v1/shipments?page=1",
"last": null,
"prev": null,
"next": "https://app.artport.co/api/v1/shipments?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://app.artport.co/api/v1/shipments",
"per_page": 20,
"to": 20
}
}
```
# Get Shipment
Source: https://developers.artport.co/guide/api/shipments/show
export const action_0 = "retrieve"
### Overview
This endpoint can be used to get a single shipment.
Endpoint: `/api/v1/shipments/{shipment_id}`
Method: `GET`
### URL Parameters
The ID of the shipment you wish to { action_0 }.
### Response
If the shipment is successfully retrieved, the API will return a `200 OK` status code.
The response will contain the following content:
An array containing a single [Shipment](/guide/schemas/shipment) object.
```json 200 theme={"system"}
{
"data": {
"id": 1,
"title": "Secured local capability",
"value": 7431,
"status": 2,
"box": 2,
"length": 37,
"height": 21,
"depth": 1,
"service": 1,
"fulfillment_address": {
"id": 2,
"name": "Gaylord-Ratke",
"email": "warren25@hotmail.com",
"phone": "+12069536978",
"line_1": "684 Kiley Cape",
"line_2": "Suite 269",
"city": "Bednarburgh",
"region": "Idaho",
"post_code": "29709",
"country": 1,
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
},
"destination_address": {
"id": 3,
"name": "Weissnat-Larkin",
"email": "weimann.aylin@gmail.com",
"phone": "+12069536978",
"line_1": "141 Chaim Mountains",
"line_2": "Apt. 556",
"city": "Lake Kamron",
"region": "South Dakota",
"post_code": "43650-3558",
"country": 1,
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
},
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
}
}
```
# Update Shipment
Source: https://developers.artport.co/guide/api/shipments/update
export const action_0 = "update"
### Overview
This endpoint can be used to update a shipment.
Endpoint: `/api/v1/shipments/{shipment_id}`
Method: `PATCH`
It is critical that you [verify the fulfillment and destination addresses](/guide/api/addresses/verify) before using them.
Failure to verify the addresses may result in loss or delayed shipments.
You may also be **charged** should address correction be necessary by the carrier.
### URL Parameters
The ID of the shipment you wish to { action_0 }.
### Request
When creating a shipment, you can use either of the following two approaches to specify the fulfillment and destination addresses:
* Use the `fulfillment_address_id` and `destination_address_id` fields to reference existing addresses that have already been stored on ArtPort.
* Provide the address details directly in the `fulfillment_address` and `destination_address` fields.
You can also combine these approaches. For example, by using a `fulfillment_address_id` and a `destination_address`, or vice versa.
For examples of how to use these fields, see the request examples on this page.
The name or a brief description of the piece. You can also use an internal reference number.
Minimum character length: `2`
Maximum character length: `50`
The value of the artwork in USD \$.
Always use an accurate value to make sure that any insurance claims are properly honored.
Minimum value: `50`
Maximum value: `10000`
The length of the piece in inches.
Minimum length: `17`
Maximum length: `44`
The height of the piece in inches.
Minimum height: `13`
Maximum height: `34`
The depth of the piece in inches.
Minimum depth: `1`
Maximum depth: `4`
A [Service](/guide/enums/services) enum representing the service to be used for the shipment.
The ID of an existing address to be used as the fulfillment address.
This field is required if the `fulfillment_address` field is not provided.
An object containing the fulfillment address details.
This field is required if the `fulfillment_address_id` field is not provided.
For example, "John Smith" or "Acme Products".
Minimum character length: `2`
Maximum character length: `50`
The contact email address.
Carriers may send one or more shipment tracking notifications to this email address.
Minimum character length: `6`
Maximum character length: `100`
The contact phone number.
This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).
Minimum character length: `7`
Maximum character length: `30`
Line 1 of the address.
Minimum character length: `2`
Maximum character length: `35`
Line 2 of the address.
Minimum character length: `2`
Maximum character length: `35`
The address' town or city.
Minimum character length: `2`
Maximum character length: `35`
The address' state, province, or region.
Minimum character length: `2`
Maximum character length: `30`
The address' post code.
Minimum character length: `2`
Maximum character length: `16`
A [Country](/guide/enums/countries) enum representing the address' country.
The ID of an existing address to be used as the destination address.
This field is required if the `destination_address` field is not provided.
An object containing the destination address details.
This field is required if the `destination_address_id` field is not provided.
For example, "John Smith" or "Acme Products".
Minimum character length: `2`
Maximum character length: `50`
The contact email address.
Carriers may send one or more shipment tracking notifications to this email address.
Minimum character length: `6`
Maximum character length: `100`
The contact phone number.
This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).
Minimum character length: `7`
Maximum character length: `30`
Line 1 of the address.
Minimum character length: `2`
Maximum character length: `35`
Line 2 of the address.
Minimum character length: `2`
Maximum character length: `35`
The address' town or city.
Minimum character length: `2`
Maximum character length: `35`
The address' state, province, or region.
Minimum character length: `2`
Maximum character length: `30`
The address' post code.
Minimum character length: `2`
Maximum character length: `16`
A [Country](/guide/enums/countries) enum representing the address' country.
### Response
If the shipment is successfully updated, the API will return a `204 No Content` status code.
The response will not contain any content.
```json Request (with address IDs) theme={"system"}
{
"title": "Test Shipment",
"value": 1000,
"length": 17,
"height": 13,
"depth": 1,
"service": 1,
"fulfillment_address_id": 123,
"destination_address_id": 456
}
```
```json Request (with address details) theme={"system"}
{
"title": "Test Shipment",
"value": 1000,
"length": 17,
"height": 13,
"depth": 1,
"service": 1,
"fulfillment_address": {
"name": "Schaefer, Nolan and Wehner",
"email": "dave45@gmail.com",
"phone": "+12069536978",
"line_1": "492 Quitzon Avenue Apt. 157",
"line_2": "Apt. 027",
"city": "Gustside",
"region": "Massachusetts",
"post_code": "17594-7013",
"country": 1
},
"destination_address": {
"name": "Krajcik, Kuhn and Eichmann",
"email": "teresa93@gmail.com",
"phone": "+12069536978",
"line_1": "1712 Marina Ramp Suite 512",
"line_2": "Apt. 235",
"city": "Port Marlon",
"region": "Indiana",
"post_code": "62893",
"country": 1
}
}
```
```json Request (mixed) theme={"system"}
{
"title": "Test Shipment",
"value": 1000,
"length": 17,
"height": 13,
"depth": 1,
"service": 1,
"fulfillment_address": {
"name": "Schaefer, Nolan and Wehner",
"email": "dave45@gmail.com",
"phone": "+12069536978",
"line_1": "492 Quitzon Avenue Apt. 157",
"line_2": "Apt. 027",
"city": "Gustside",
"region": "Massachusetts",
"post_code": "17594-7013",
"country": 1
},
"destination_address_id": 123
}
```
```text 204 theme={"system"}
No Content
```
# Formatting
Source: https://developers.artport.co/guide/concepts/formatting
Explore the formats and conventions used in the ArtPort API
### Overview
The ArtPort API uses a variety of formats and conventions to ensure consistency across its endpoints. This guide provides an overview of the formats you can expect to encounter when working with the API.
### Timestamp Format
All timestamps returned by the ArtPort API use the given format:
```
YYYY-MM-DD HH:MM:SS
```
For example, a timestamp representing "Monday, December 9, 2024 at 4:30pm" would be formatted as:
```
2024-12-09 16:30:00
```
All timestamps use the Coordinated Universal Time (**UTC**) timezone.
### Phone Numbers
ArtPort uses the E.164 standard for recording and displaying phone numbers. This standard requires that a number formatted like so:
#### Rules
1. It must begin with a `+` symbol prefix.
2. It must include the country code.
3. It must exclude any leading zeros.
4. It must include the area code.
5. It must include all remaining digits.
6. It must not include internal routing e.g. office extensions.
7. It must not include any other characters e.g. spaces or hyphens.
#### Examples
The following table demonstrates how a locally-formatted number in a particular country should be written to be E.164-compliant:
| Country | Local | E.164 |
| ----------- | ------------ | ------------- |
| Australia | 0491 570 159 | +61491570159 |
| Canada | 206-953-6978 | +12069536978 |
| Ireland | 0889 105 586 | +353889105586 |
| New Zealand | 09 567 4562 | +64495674562 |
| UK | 07158 656473 | +447158656473 |
| USA | 206-953-6978 | +12069536978 |
# Pagination
Source: https://developers.artport.co/guide/concepts/pagination
Explore how to use pagination with the ArtPort API
### Overview
The ArtPort API uses limit-offset pagination for some of its endpoints. This allows you to retrieve a subset of the total data available, which can be useful when working with large datasets.
Any endpoints that support pagination will be indicated in the documentation.
#### Setting the Page Number
To retrieve a specific page of data, you can use the `page` query parameter. For example, to retrieve the second page of data, you could use the following path:
```
/api/v1/shipments?page=2
```
If no `page` query parameter is passed, the API will default to the first page.
#### Customizing the Page Size
By default, paginated endpoints will return **20 items per page**. However, this can be customized by passing a `limit` query parameter. For example, to retrieve 50 items per page, you could use the following path:
```
/api/v1/shipments?limit=50
```
If a `limit` query parameter is passed, then it must be an integer between `1` and `50`.
#### Paginated Response Structure
Paginated responses use the following structure:
```json Example Response Structure theme={"system"}
{
"data": [
{
"id": 1,
"title": "Shipment One",
// ...
},
{
"id": 2,
"title": "Shipment Two",
// ...
}
],
"links": {
"first": "https://app.artport.co/api/v1/shipments?page=1",
"last": null,
"prev": null,
"next": "https://app.artport.co/api/v1/shipments?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://app.artport.co/api/v1/shipments",
"per_page": 20,
"to": 20
}
}
```
The items returned in the current page. If no items are returned, this will be an empty array.
URLs for the first, last, previous, and next pages.
The URL for the first page.
The URL for the last page. This will always be `null`.
The URL for the previous page. This will be `null` if the current page is the first page.
The URL for the next page. This will be `null` if the current page is the last page.
Metadata about the current page.
The current page number.
The starting index of the items on the current page. For example, if the page size is `20`, and the second page has been returned, this will be `21`.
The base URL for the endpoint, excluding any pagination parameters.
The number of items per page.
The ending index of the items on the current page. For example, if the page size is `20`, and the second page has been returned, this will be `40`.
# Rate Limiting
Source: https://developers.artport.co/guide/concepts/rate-limiting
Explore the limitations and guidelines
### Overview
In order to ensure that the API remains stable for all customers, we enforce a limit on the number of requests that can be sent.
The API limit is currently 20 requests per minute.
### Exceeding the limit
If you send more than the permitted number of requests per minute, then those requests will be rejected. Until the limit resets, all requests will receive a `429 Too Many Requests` response.
### Managing rate limits
Usually, a `429 Too Many Requests` response isn't an issue. You can just send it again in a minute or so. However, if you receive this error regularly, then you should adjust your integration so that it backs off.
### Developing a backoff strategy
When you receive a response, it will include the following headers that indicate your current usage of the API:
| Header | Description |
| --------------------- | ---------------------------------------------------- |
| X-RateLimit-Limit | The number of requests that can be sent per minute. |
| X-RateLimit-Remaining | The number of requests that can be sent this minute. |
If you exceed the API rate limit, then the following headers will also be present in the response:
| Header | Description |
| ----------------- | ------------------------------------------------- |
| Retry-After | Seconds remaining until new requests can be sent. |
| X-RateLimit-Reset | The unix timestamp when new requests can be sent. |
#### Tips
You can use `X-RateLimit-Remaining` to avoid hitting the rate limit. If you don't have any requests available, then there is no point sending one as it will return a `429 Too Many Requests` response.
If you hit the rate limit / receive a `429 Too Many Requests` response, then you can use `Retry-After` or `X-RateLimit-Reset` to determine when it is suitable to send additional requests to the API.
# Requests
Source: https://developers.artport.co/guide/concepts/requests
Connect to the API and send requests
### Overview
ArtPort authenticates your API requests using your organization's API token, which must be included every time.
Requests without a token will return a `401 Unauthorized` response.
In order to use the API, your organization requires a subscription. If you do not have a subscription, then all requests will return a `402 Payment Needed` response.
### Authorization
To authenticate, supply your API token in the request's header. You should configure the header so it uses `bearer` authentication e.g.
```php theme={"system"}
request.headers.authorization = 'Bearer 2xH8eAQR...';
```
### Headers and Format
The ArtPort API accepts request bodies in JSON format. When sending a request, you should include the following headers to indicate that you are sending and expecting JSON:
```text theme={"system"}
Accept: application/json
Content-Type: application/json
```
# Responses
Source: https://developers.artport.co/guide/concepts/responses
How to handle responses from the ArtPort API
### Overview
The ArtPort API returns responses in JSON format and uses HTTP status codes to indicate the success or failure of a request.
For example, a successful request to retrieve an address will return a response with a `200` status code and the following body:
```json theme={"system"}
{
"data": {
"id": 1,
"name": "Kohler Group",
"email": "art.port.example@example.com",
"phone": "+123456789",
"line_1": "123 Example Street",
"line_2": "Apt. 300",
"city": "Moenburgh",
"region": "Colorado",
"post_code": "72099",
"country": 1,
"created_at": "2024-12-09 13:49:57",
"updated_at": "2024-12-09 13:49:57"
}
}
```
# Address Verification Status
Source: https://developers.artport.co/guide/enums/address-verification-status
### Overview
The following enum values represent the address verification status that can be returned by the ArtPort API:
| ID | Status | Description |
| -- | ------------ | --------------------------------------------------------------------------- |
| 0 | Rate Limited | ArtPort has hit the rate limit of the external address verification system. |
| 1 | Unverified | Something went wrong while checking the address. |
| 2 | Invalid | A matching address could not be found. |
| 3 | Recommended | The address was not found, but a similar one exists. |
ArtPort makes use of external services to verify addresses.
A `0 (Rate Limited)` status does not indicate that your request to ArtPort was rate limited, but that ArtPort's request to the external service was rate limited.
Unfortunately, ArtPort cannot provide more information about this rate limiting. Therefore, it's recommended to use a backoff strategy and retry the request after a short delay.
# Box Types
Source: https://developers.artport.co/guide/enums/box-types
### Overview
The following enum values represent the box types that are supported by the ArtPort API:
| ID | Box Type | Description |
| -- | -------- | ------------------------------------------- |
| 1 | Small | Up to 22in (L) x 18in (W) x 4in (H) - 45lbs |
| 2 | Medium | Up to 36in (L) x 24in (W) x 4in (H) - 45lbs |
| 3 | Large | Up to 44in (L) x 34in (W) x 4in (H) - 45lbs |
# Carriers
Source: https://developers.artport.co/guide/enums/carriers
### Overview
The following enum values represent the carriers that are supported by the ReturnPilot API:
| ID | Carrier |
| -- | ------- |
| 1 | DHL |
| 2 | FedEx |
| 3 | UPS |
# Checkout Session Status
Source: https://developers.artport.co/guide/enums/checkout-session-status
### Overview
The following enum values represent the checkout session status that can be returned by the ArtPort API:
| ID | Status | Description |
| -- | ------------ | ------------------------------------------------------------------------------ |
| 0 | Rate Limited | ArtPort has hit the rate limit of the external shipment rate lookup system. |
| 1 | Failed | ArtPort was unable to fetch carrier rates from the external system. Try again. |
ArtPort makes use of external services to determine shipment rates.
A `0 (Rate Limited)` status does not indicate that your request to ArtPort was rate limited, but that ArtPort's request to the external service was rate limited.
Unfortunately, ArtPort cannot provide more information about this rate limiting. Therefore, it's recommended to use a backoff strategy and retry the request after a short delay.
# Countries
Source: https://developers.artport.co/guide/enums/countries
### Overview
The following enum values represent the countries that are supported by the ArtPort API:
| ID | Country |
| -- | ------------------------ |
| 1 | United States of America |
# Services
Source: https://developers.artport.co/guide/enums/services
### Overview
The following enum values represent the services that are supported by the ArtPort API:
| ID | Services | Description |
| -- | --------- | ---------------------------------------------------------------------------- |
| 1 | Standard | Slower, but at a reduced price. Estimated transit per journey is 2 - 4 days. |
| 2 | Expedited | Faster, but at a higher price. Estimated transit per journey is 1 - 2 days. |
# Shipment Status
Source: https://developers.artport.co/guide/enums/shipment-status
### Overview
The following enum values represent the shipment statuses that are supported by the ArtPort API:
| ID | Shipment Status | Description |
| -- | --------------- | ----------------------------------------------------------- |
| 1 | Draft | The shipment is ready. Proceed to checkout to complete. |
| 2 | Confirmed | Purchase confirmed, shipment is now awaiting assignment. |
| 3 | Pending | Shipment has been assigned to a warehouse for processing. |
| 4 | Allocated | Shipment is being prepared at the distribution warehouse. |
| 5 | Scheduled | Shipment scheduled for delivery to fulfillment address. |
| 6 | Dispatched | Shipment is currently en-route to the fulfillment address. |
| 7 | Delivered | Shipment has been delivered to fulfillment address. |
| 8 | Filed | Condition report received, shipping label is being created. |
| 9 | Drop-Off | Artwork can now be taken to a suitable drop-off location. |
| 10 | Shipped | Artwork has been collected and is en-route to destination. |
| 11 | Arrived | Artwork successfully delivered to the destination address. |
| 11 | Completed | Artwork arrival condition report has been received. |
# Introduction
Source: https://developers.artport.co/guide/getting-started/introduction
Welcome to the ArtPort Developer Portal.
### Overview
This developer portal contains the documentation required to assist software developers in working with the ArtPort API. Follow the steps below to get started building your integration.
The ArtPort API is currently invite only. If you have any questions or feedback, please contact us via the ArtPort support center.
If you encounter a problem or issue while using the API, then please contact us via the ArtPort support center.
# Updates
Source: https://developers.artport.co/guide/getting-started/updates
Review API and documentation changelog
### Overview
All of the changes made to the API or to the developer portal can be found below. Whilst we endeavor not to introduce breaking changes into the API, we cannot guarantee this. Therefore, we recommend that you review this page occasionally in order to stay up to date.
Initial release.
# Address
Source: https://developers.artport.co/guide/schemas/address
ID of the address.
For example, "John Smith" or "Acme Products".
The contact email address.
Carriers may send one or more shipment tracking notifications to this email address.
The contact phone number.
This must be formatted using the [E.164 standard](/guide/concepts/formatting#phone-numbers).
Line 1 of the address.
Line 2 of the address.
The address' town or city.
The address' state, province, or region.
The address' post code.
A [Country](/guide/enums/countries) enum representing the address' country.
Timestamp of when the address was created.
Timestamp of when the address was last updated.
```json Example Address Structure theme={"system"}
{
"id": 1,
"name": "Kohler Group",
"email": "parisian.kristoffer@yahoo.com",
"phone": "+12069536978",
"line_1": "193 Dach Shores Suite 632",
"line_2": "Apt. 300",
"city": "Moenburgh",
"region": "Colorado",
"post_code": "72099",
"country": 1,
"created_at": "2024-12-09 22:49:57",
"updated_at": "2024-12-09 22:49:57"
}
```
# Shipment
Source: https://developers.artport.co/guide/schemas/shipment
ID of the shipment.
The name or a brief description of the piece.
The value of the artwork in USD \$.
A [Shipment Status](/guide/enums/shipment-status) enum representing the status of the shipment.
A [Box Type](/guide/enums/box-types) enum representing the box to be used for the shipment.
The length of the piece in inches.
The height of the piece in inches.
The depth of the piece in inches.
A [Service](/guide/enums/services) enum representing the service to be used for the shipment.
An [Address](/guide/schemas/address) object which represents the fulfillment address.
An [Address](/guide/schemas/address) object which represents the destination address.
The total price in U.S. Dollars to send the artwork.
A [Carrier](/guide/enums/service) enum representing the provider handling the first journey of the shipment (sending empty box to fulfillment address).
The tracking number for the first journey of the shipment.
The URL to the tracking page for the first journey of the shipment.
A [Carrier](/guide/enums/service) enum representing the provider handling the second journey of the shipment (sending packed box to destination address).
The tracking number for the second journey of the shipment.
The URL to the tracking page for the second journey of the shipment.
Timestamp of when the shipment was created.
Timestamp of when the shipment was last updated.
```json Example Shipment Structure theme={"system"}
{
"id": 1,
"title": "Secured local capability",
"value": 7431,
"status": 2,
"box": 2,
"length": 37,
"height": 21,
"depth": 1,
"service": 1,
"fulfillment_address": {
"id": 2,
"name": "Gaylord-Ratke",
"email": "warren25@hotmail.com",
"phone": "+12069536978",
"line_1": "684 Kiley Cape",
"line_2": "Suite 269",
"city": "Bednarburgh",
"region": "Idaho",
"post_code": "29709",
"country": 1,
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
},
"destination_address": {
"id": 3,
"name": "Weissnat-Larkin",
"email": "weimann.aylin@gmail.com",
"phone": "+12069536978",
"line_1": "141 Chaim Mountains",
"line_2": "Apt. 556",
"city": "Lake Kamron",
"region": "South Dakota",
"post_code": "43650-3558",
"country": 1,
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
},
"price": 245,
"journey_1_carrier": 2,
"journey_1_tracking_number": "AX56",
"journey_1_tracking_page_url": "https://carrier2.com/track/AX56",
"journey_2_carrier": 3,
"journey_2_tracking_number": "JR87",
"journey_2_tracking_page_url": "https://carrier3.com/track/JR87",
"created_at": "2024-12-09 15:39:37",
"updated_at": "2024-12-09 15:39:37"
},
```