To work with agreements it is first important to understand the fulfilment agreement lifecycle. The agreement lifecycle has four states: new, priced, active and cancelled (priced is sometimes alternatively termed as 'sent').
Agreements are always initiated by the customer, which means there is no way for a fulfilment provider to initiate an agreement. Once you have spoken with your Smart Gift representative and have established your offerings, these become available for potential customers to enquire about. They are able to do this through the Smart Gift dashboard, your offering is presented with the name ans description you provide, as well as the type of service it is.
Once a customer has selected your fulfilment method, you will be sent an email and this initiated agreement will be shown when you query the agreements endpoint. At this point there is no price suggested or agreed and the prospective customer is made aware that no agreement is in place until it has been confirmed. In this state, the agreement is 'new'.
You are now able to respond to this request by providing a price and price_type. Orders in Smart Gift have one destination for delivery but may contain multiple items. At this time, the delivery method applies to the order and not to specific items within the order. The price_type option allows you to state whether the price given is per order or per-item. Once you have used the API to provide this information, the agreement state changes to 'priced' or 'sent'.
At this point, the customer will receive an email to alert them that you have priced the service and at this point they can accept or terminate the agreement. If they accept the agreement, it will enter the 'active' states, if they reject it, it will enter the 'terminated' or 'cancelled' state. Additionally, either party can also terminate an agreement if required.
| Field | Type | Description |
|---|---|---|
| id | integer | The id of the agreement |
| company_id | integer | The id of the company |
| company_name | string | The name of the company |
| company_phone | string | The phone number of the company |
| contact_name | string | The name of the contact |
| contact_email | string | The email of the contact |
| delivery_method_id | integer | The id of the delivery method that this fulfilment option is for |
| delivery_method_name | string | The name of the delivery method that this fulfilment option is for |
| fulfilment_option_id | integer | The id of the fulfilment option the customer is requesting |
| fulfilment_option_name | string | The name of the fulfilment option the customer is requesting |
| price | decimal | The price of the fulfilment, propsed by the provider, accepted by the customer |
| price_type | string | The type of price, either 'per_order' or 'per_item' or 'not_set' if not yet set |
| initiated_at | string | The date and time the agreement was initiated by the customer |
| priced_at | string | The date and time the agreement was priced by the provider |
| accepted_at | string | The date and time the agreement was accepted by the customer |
| terminated_at | string | The date and time the agreement was terminated |
| status_text | string | The status of the agreement, either 'new', 'sent', 'active', or 'cancelled' |
GET REQUEST (/fulfilment/agreements?status=new|sent|active|cancelled)
Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXXYou can supply a query parameter to filter agreements by their state. States include new, sent, active and cancelled.
[
{
"id": 6,
"company_id": 60,
"company_name": "Example Company",
"company_phone": null,
"contact_name": "John",
"contact_email": "john@examplecompany.com",
"delivery_method_id": 97,
"delivery_method_name": "Gift Letter",
"fulfilment_option_id": 3,
"fulfilment_option_name": "A4 Letter Delivery",
"price": null,
"price_type": "not_set",
"initiated_at": "2024-11-20 13:19:52",
"priced_at": null,
"accepted_at": null,
"terminated_at": null
},
{
"id": 7,
"company_id": 60,
"company_name": "Example Company",
"company_phone": null,
"contact_name": "Jill",
"contact_email": "jill@examplecompany.com",
"delivery_method_id": 97,
"delivery_method_name": "Carrier Pigeon",
"fulfilment_option_id": 3,
"fulfilment_option_name": "Gift Box",
"price": null,
"price_type": "not_set",
"initiated_at": "2024-11-20 13:22:27",
"priced_at": null,
"accepted_at": null,
"terminated_at": null
}
]PUT REQUEST (/fulfilment/agreements/{agreementId}/price)
Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXX
{
"price": 3.40,
"price_type": 1
}
Pricing an agreement is how you communicate to the customer what they will pay per order or per item. The price_type
represents what your price applies to (either the entire order, or each item in the order), and the price is the
amount you commit to fulfil each order/item for. This defaults to per-order if not supplied.
1 = "per_order"
2 = "per_item"
{
"price": 3.40,
"price_type": "per_order"
}
You may also pass the string versions of these if preferred.
{
"id": 6,
"company_id": 60,
"company_name": "Example Company",
"company_phone": null,
"contact_name": "John",
"contact_email": "john@examplecompany.com",
"delivery_method_id": 97,
"delivery_method_name": "Gift Letter",
"fulfilment_option_id": 3,
"fulfilment_option_name": "A4 Letter Delivery",
"price": 3.4,
"price_type": "per_order",
"initiated_at": "2024-11-20 13:19:52",
"priced_at": "2024-11-27T12:34:04.453427Z",
"accepted_at": null,
"terminated_at": null,
"status_text": "sent"
}The response includes an object representing the updated fulfilment agreement. The priced_at field will contain the time that the price was supplied, the price and price_type fields will contain the data sent in the request.
PUT REQUEST (/fulfilment/agreements/{agreementId}/terminate)
Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXX
{
"reason": "Retiring this contract to begin another.. "
}
Terminating an agreement brings an agreement to the end of its lifecycle. It may occur at any time and be actioned by either side. A fulfilment provider may terminate a new agreement because it is unable to take any new customers at the time, a customer may terminate the agreement rather than agreeing to it if an agreement on price cannot be reached, and even if an agreement is reached, it is likely that an agreement will need to be revised over the course of the relationship due to increases in cost. It is recommended to supply a reason for terminating an agreement, this improves clarity between parties and will likely be helpful when looking back at this data in the future.
{
"id": 6,
"company_id": 60,
"company_name": "Example Company",
"company_phone": null,
"contact_name": "John",
"contact_email": "john@examplecompany.com",
"delivery_method_id": 97,
"delivery_method_name": "Gift Letter",
"fulfilment_option_id": 3,
"fulfilment_option_name": "A4 Letter Delivery",
"price": 3.4,
"price_type": "per_order",
"initiated_at": "2024-11-20 13:19:52",
"priced_at": "2024-11-27T12:34:04.453427Z",
"accepted_at": "2024-11-29T12:37:03.423443Z",
"terminated_at": "2025-06-22T12:14:06.000000Z",
"status_text": "cancelled"
}The response includes an object representing the updated fulfilment agreement. The terminated_at field will contain the time that the agreement was terminated.
Error responses related to Fulfilment Agreements are typically a result of an invalid filter value being passed in with the API request, however they may also be returned due to invalid configurations or if an unexpected error occurs. Please review Error Responses for guidance on dealing with errors.