Gift Options API

Manage the gift options a site offers, such as gift wrapping or a gift box.
At checkout a buyer can add one gift option to an order, shown with its photo
and price, and its price is added to the order total. Each site has its own
options, up to 20.

Whether buyers can also write a gift note, and how long it can be, are site
settings: gift_notes_enabled and gift_note_max_length on the
site. An order records the option and note the buyer chose in
its gift_option and gift_note fields; see Orders.

Endpoints

• List Gift Options - GET /api/v1/sites/{site_id}/gift-options/
• Create Gift Option - POST /api/v1/sites/{site_id}/gift-options/
• Get Gift Option - GET /api/v1/sites/{site_id}/gift-options/{gift_option_id}/
• Update Gift Option - PUT /api/v1/sites/{site_id}/gift-options/{gift_option_id}/
• Delete Gift Option - DELETE /api/v1/sites/{site_id}/gift-options/{gift_option_id}/
• Set Gift Option Image - PUT /api/v1/sites/{site_id}/gift-options/{gift_option_id}/image/
• Remove Gift Option Image - DELETE /api/v1/sites/{site_id}/gift-options/{gift_option_id}/image/

Changing or deleting a gift option never changes an order that already has
it. A shopper whose cart holds it sees the change when they next load
checkout, and a deleted or disabled option is dropped from their cart.

List Gift Options

Retrieve every gift option of a site, ordered by position, then by when
they were created. A site has at most 20, so the list isn't paginated and
has_more is always false.

Endpoint: GET /api/v1/sites/{site_id}/gift-options/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/gift-options/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "gft_d0b6fmv28q6vn14peug1",
      "name": "Gift wrap",
      "description": "Kraft paper with a cotton ribbon.",
      "price": 500,
      "enabled": true,
      "position": 0,
      "image": {
        "id": "img_d0b6fmv28q6vn14peui1",
        "url": "/images/img_d0b6fmv28q6vn14peui1-large.jpeg"
      },
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ],
  "has_more": false
}

Create Gift Option

Add a gift option to a site. Add its photo afterward with
Set Gift Option Image.

Endpoint: POST /api/v1/sites/{site_id}/gift-options/

Permission Required: Write

Request Body

{
  "name": "Gift wrap",
  "description": "Kraft paper with a cotton ribbon.",
  "price": 500,
  "enabled": true,
  "position": 0
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/gift-options/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "name": "Gift wrap",
    "description": "Kraft paper with a cotton ribbon.",
    "price": 500,
    "enabled": true,
    "position": 0
  }'

Response

Status: 201 Created

{
  "id": "gft_d0b6fmv28q6vn14peug1",
  "name": "Gift wrap",
  "description": "Kraft paper with a cotton ribbon.",
  "price": 500,
  "enabled": true,
  "position": 0,
  "image": null,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Missing name

Status: 400 Bad Request

{
  "error": "name is required",
  "code": "MISSING_FIELD"
}

Invalid field, such as a negative price or a position over 1000

Status: 400 Bad Request

{
  "error": "Price must be zero or more",
  "code": "INVALID_FIELD"
}

The site already has 20 gift options

Status: 400 Bad Request

{
  "error": "A site can have at most 20 gift options",
  "code": "INVALID_FIELD"
}

Duplicate name

Status: 409 Conflict

{
  "error": "Resource already exists",
  "code": "DUPLICATE"
}

Get Gift Option

Retrieve a single gift option.

Endpoint: GET /api/v1/sites/{site_id}/gift-options/{gift_option_id}/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/gift-options/gft_d0b6fmv28q6vn14peug1/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

Returns a Gift Option Object. A gift option of another
site returns 404 Not Found.

Update Gift Option

Replace a gift option's fields. Send every field; one left out takes its
default, except position, which stays where it is when left out. The
image is kept. Merchants reorder options with arrows in the dashboard,
which renumbers a site's options from 0.

Endpoint: PUT /api/v1/sites/{site_id}/gift-options/{gift_option_id}/

Permission Required: Write

Request Body

The same fields as Create Gift Option.

Request

curl -X PUT "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/gift-options/gft_d0b6fmv28q6vn14peug1/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{
    "name": "Gift wrap",
    "description": "Kraft paper with a silk ribbon.",
    "price": 600,
    "enabled": true,
    "position": 0
  }'

Response

Status: 204 No Content

Delete Gift Option

Delete a gift option and its photo. Orders that included it keep it. To stop
offering it without deleting it, update it with enabled set to false.

Endpoint: DELETE /api/v1/sites/{site_id}/gift-options/{gift_option_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/gift-options/gft_d0b6fmv28q6vn14peug1/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Set Gift Option Image

Upload the photo shown beside the gift option at checkout, replacing any it
had. Send a JPEG or PNG as multipart/form-data in the image field, up to
50 MB, the same as product images.

Endpoint: PUT /api/v1/sites/{site_id}/gift-options/{gift_option_id}/image/

Permission Required: Write

Request

curl -X PUT "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/gift-options/gft_d0b6fmv28q6vn14peug1/image/" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "image=@gift-wrap.jpg"

Response

Status: 200 OK

Returns the updated Gift Option Object.

Error Responses

No file in the image field

Status: 400 Bad Request

{
  "error": "image is required",
  "code": "MISSING_FIELD"
}

Remove Gift Option Image

Remove a gift option's photo.

Endpoint: DELETE /api/v1/sites/{site_id}/gift-options/{gift_option_id}/image/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/sites/sit_d0b6fmv28q6vn14peun0/gift-options/gft_d0b6fmv28q6vn14peug1/image/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Gift Option Object

Fields