Services API v1 Use Case Guide

Help service providers get and modify their service orders.

API Version: v1

What is the Services API?

With the Selling Partner API for Services (Services API), you can

Access service job details.
Confirm or reschedule appointments.
Set appointment resource assignments.
Set job fulfillment data.
Set resource capacity schedules that drive appointment availability for customers.
Integrate services data for route and fulfillment planning.

After fulfillment, service sellers can audit resource (for example, technician) performance by tracking on-time start, service job completion within appointment windows, no-shows, and fulfillment breaks.

Post fulfillment, the Services API can measure seller and resource performance, set up payment dashboards for sellers, and analyze the actual demand against resource capacity schedules.

Operations in the Services API

The operations in the Services API fall into four categories:

Category	Operations
Getting Service Job Data	`getServiceJobs` `getServiceJobByServiceJobId`
Setting Service Job Appointments and Assigning Appointment Resources	`addAppointmentForServiceJobByServiceJobId` `rescheduleAppointmentForServiceJobByServiceJobId` `assignAppointmentResources`
Closing Service Jobs	`setAppointmentFulfillmentData` `createServiceDocumentUploadDestination` `completeServiceJobByServiceJobId` `cancelServiceJobByServiceJobId`
Setting Service Job Resource Capacity Schedules	`updateSchedule` `createReservation` `updateReservation` `cancelReservation`

The combination of operations a service seller requires depends on the specific case arranged between them and their Amazon business line partners.

For example, the operations in the Closing Service Jobs category may not be able to substitute for a field technician using an Amazon-required mobile app. Service sellers should consult their relevant Amazon business line partners to settle appropriate API usage scope before initiating integration with the Services API.

Selling Partner API roles

To access the Services API, you must have the Professional Services role.

You can request the Professional Services role when you register as a developer, or by updating your existing Developer Profile. To do this:

In the Roles section of the Developer Profile form, select the Professional Services checkbox.
In the text box in the Use Cases section, indicate the program name for which you want to use the Services API.
Select Register to submit your request. A support case is automatically created for you.

You will be contacted with next steps through your support case. You can access your support case in the Case Log in Seller Central.

When you register your application, choose the Professional Services role. For more information about roles, refer to Roles in the Selling Partner API.

Tutorial: Getting Service Job data

Learn how to obtain Service Job data to determine the Jobs that require a service seller to take action and the Jobs that need additional API calls.

Obtain Service Job data with the following operations:

getServiceJobs responds with a list of Service Jobs as constrained by filter inputs.
getServiceJobByServiceJobId responds with Service Job details using Service Job IDs that getServiceJobs returns, or that the Seller Central Manage Jobs Download CSV Report file contains.

Prerequisites

To complete this tutorial, you need:

Authorization from the seller for whom you are making calls. Refer to Authorizing Selling Partner Applications for more information.
The Professional Services role.

Step 1. Get all jobs created or updated during a time frame that you specify

The getServiceJobs operation:

Gets the status of service jobs and appointments.
Flags appointments that need a resource assignment, such as a technician.
Manages route and fulfillment planning.

After fulfillment, you can use this operation along with getServiceJobByServiceJobId to audit technician performance.

Parameters

Type	Name	Description	Schema
Query	`serviceOrderIds` optional	List of service order ids for the query you want to perform.Max values supported 20. Min count : 1 Max count : 20	< string > array
Query	`serviceJobStatus` optional	A list of one or more job status by which to filter the list of jobs.	< enum (`ServiceJobStatus`) > array
Query	`pageToken` optional	String returned in the response of your previous request.	string
Query	`pageSize` optional	A non-negative integer that indicates the maximum number of jobs to return in the list, Value must be 1 - 20. Default 20. Minimum : 1 Maximum : 20	integer
Query	`sortField` optional	Sort fields on which you want to sort the output.	enum (`SortField`)
Query	`sortOrder` optional	Sort order for the query you want to perform.	enum (`SortOrder`)
Query	`createdAfter` optional	A date used for selecting jobs created at or after a specified time. Must be in ISO 8601 format. Required if `LastUpdatedAfter` is not specified. Specifying both `CreatedAfter` and `LastUpdatedAfter` returns an error.	string
Query	`createdBefore` optional	A date used for selecting jobs created at or before a specified time. Must be in ISO 8601 format.	string
Query	`lastUpdatedAfter` optional	A date used for selecting jobs updated at or after a specified time. Must be in ISO 8601 format. Required if `createdAfter` is not specified. Specifying both `CreatedAfter` and `LastUpdatedAfter` returns an error.	string
Query	`lastUpdatedBefore` optional	A date used for selecting jobs updated at or before a specified time. Must be in ISO 8601 format.	string
Query	`scheduleStartDate` optional	A date used for filtering jobs schedules at or after a specified time. Must be in ISO 8601 format. Schedule end date should not be earlier than schedule start date.	string
Query	`scheduleEndDate` optional	A date used for filtering jobs schedules at or before a specified time. Must be in ISO 8601 format. Schedule end date should not be earlier than schedule start date.	string
Query	`marketplaceIds` required	Used to select jobs that were placed in the specified marketplaces. Max count : 1	< string > array
Query	`asins` optional	List of Amazon Standard Identification Numbers (ASIN) of the items. Max values supported is 20. Min count : 1 Max count : 20	< string > array
Query	`requiredSkills` optional	A defined set of related knowledge, skills, experience, tools, materials, and work processes common to service delivery for a set of products or service scenarios. Max values supported is 20. Min count : 1 Max count : 20	< string > array
Query	`storeIds` optional	List of Amazon-defined identifiers for the region scope. Max values supported is 50. Min count : 1 Max count : 50	< string > array

Request example

GET https://sellingpartnerapi-na.amazon.com/service/v1/serviceJobs?scheduleStartDate=2020-08-11T19:10:02&createdAfter=2020-08-14T12:10:02&marketplaceIds=ATVPDKIKX0DER

Response

A successful response includes the following elements:

Name	Description	Schema
`totalResultSize`	Total result size of the query result.	integer
`nextPageToken`	A generated string used to pass information to your next request. If `nextPageToken` is returned, pass the value of `nextPageToken` to the `pageToken` to get next results.	string
`previousPageToken`	A generated string used to pass information to your next request. If `previousPageToken` is returned, pass the value of `previousPageToken` to the `pageToken` to get previous page results.	string
`jobs`	List of job details for the given input.	< `ServiceJob` > array

Response example for an active job with no appointment

{
  "payload": {
    "totalResultSize": 52,
    "nextPageToken": "eyJmaXJzdFJlY29yZCI6eyJpbmRleCI6MH0sImxhc3RSZWNvcmQiOnsiaW5kZXgiOjE0fX0%3D",
    "jobs": [
      {
        "serviceJobId": "f4ba15dc-5da3-9405-143e-7faa5a5a4bd6",
        "serviceJobStatus": "PENDING_SCHEDULE",
        "serviceOrderId": "903-3260627-5237451",
        "storeId": "1c30b3ab-1c1e-40e9-bd12-910274cf65d4",
        "scopeOfWork": {
          "asin": "B06X1CG62R",
          "requiredSkills": [
            "DEFAULT"
          ]
        },
        "createTime": "2020-08-26T17:00:28Z",
        "buyer": {
          "name": "test"
        }
      },
      {
        "serviceJobId": "d4ba15dd-2d6c-55e1-3b2c-81f2ff93cd8f",
        "serviceJobStatus": "PENDING_SCHEDULE",
        "serviceOrderId": "902-9707299-0322268",
        "storeId": "1c30b3ab-1c1e-40e9-bd12-910274cf65d4",
        "scopeOfWork": {
          "asin": "B06X1CG62R",
          "requiredSkills": [
            "DEFAULT"
          ]
        },
        "createTime": "2020-08-26T17:00:21Z",
        "buyer": {
          "name": "test"
        }
      }
    ]
  }
}

Response example for active jobs with active appointments

{
  "payload": {
    "totalResultSize": 50,
    "nextPageToken": "eyJmaXJzdFJlY29yZCI6eyJpbmRleCI6MH0sImxhc3RSZWNvcmQiOnsiaW5kZXgiOjE0fX0%3D",
    "jobs": [
      {
        "serviceJobId": "7eba0c8c-39f7-dff8-7df1-8ebced987641",
        "serviceJobStatus": "COMPLETED",
        "serviceOrderId": "903-1969671-6382228",
        "storeId": "1c30b3ab-1c1e-40e9-bd12-910274cf65d4",
        "scopeOfWork": {
          "asin": "B06X1CG62R",
          "requiredSkills": [
            "DEFAULT"
          ]
        },
        "createTime": "2020-08-23T00:59:59Z",
        "buyer": {
          "name": "test1"
        },
        "appointments": [
          {
            "appointmentTime": {
              "durationInMinutes": "180",
              "startTime": "2014-07-16T15:11:40Z"
            },
            "assignedTechnicians": [
              {
                "technicianId": "A1HYD3YC3Y3J4M",
                "name": "test"
              }
            ]
          }
        ]
      },
      {
        "serviceJobId": "f0ba0c94-f14e-5579-2d4a-7a2749c4144b",
        "serviceJobStatus": "COMPLETED",
        "serviceOrderId": "902-6668303-8743036",
        "storeId": "1c30b3ab-1c1e-40e9-bd12-910274cf65d4",
        "scopeOfWork": {
          "asin": "B06X1CG62R",
          "requiredSkills": [
            "DEFAULT"
          ]
        },
        "createTime": "2020-08-23T00:59:52Z",
        "buyer": {
          "name": "test2"
        },
        "appointments": [
          {
            "appointmentTime": {
              "durationInMinutes": "180",
              "startTime": "2014-07-16T15:11:40Z"
            },
            "assignedTechnicians": [
              {
                "technicianId": "A1HYD3YC3Y3J4M",
                "name": "test1"
              }
            ]
          }
        ]
      }
    ]
  }
}

Response example for a cancelled job status

{
  "payload": {
    "totalResultSize": 5,
    "nextPageToken": "eyJmaXJzdFJlY29yZCI6eyJpbmRleCI6MH0sImxhc3RSZWNvcmQiOnsiaW5kZXgiOjE0fX0%3D",
    "jobs": [
      {
        "serviceJobId": "7eba0c8c-39f7-dff8-7df1-8ebced987641",
        "serviceJobStatus": "CANCELLED",
        "serviceOrderId": "903-1969671-6382228",
        "storeId": "1c30b3ab-1c1e-40e9-bd12-910274cf65d4",
        "scopeOfWork": {
          "asin": "B06X1CG62R",
          "requiredSkills": [
            "DEFAULT"
          ]
        },
        "createTime": "2020-08-23T00:59:59Z",
        "buyer": {
          "name": "test1"
        },
        "appointments": [
          {
            "appointmentTime": {
              "durationInMinutes": "180",
              "startTime": "2014-07-16T15:11:40Z"
            },
            "assignedTechnicians": [
              {
                "technicianId": "A1HYD3YC3Y3J4M",
                "name": "test"
              }
            ]
          }
        ]
      },
      {
        "serviceJobId": "f0ba0c94-f14e-5579-2d4a-7a2749c4144b",
        "serviceJobStatus": "COMPLETED",
        "serviceOrderId": "902-6668303-8743036",
        "storeId": "1c30b3ab-1c1e-40e9-bd12-910274cf65d4",
        "scopeOfWork": {
          "asin": "B06X1CG62R",
          "requiredSkills": [
            "DEFAULT"
          ]
        },
        "createTime": "2020-08-23T00:59:52Z",
        "buyer": {
          "name": "test2"
        },
        "appointments": [
          {
            "appointmentTime": {
              "durationInMinutes": "180",
              "startTime": "2014-07-16T15:11:40Z"
            },
            "assignedTechnicians": [
              {
                "technicianId": "A1HYD3YC3Y3J4M",
                "name": "test1"
              }
            ]
          }
        ]
      }
    ]
  }
}

Step 2. Get service job details

The getServiceJobByServiceJobId operation provides service sellers access to details about their service orders and their fulfillment, including:

What orders are routed to service sellers.
Appointment and job-level statuses.
Orders that are already routed and need technician assignment.
Technician assignment gaps.

You can use this operation to determine technician on-time arrival, completion within slot, technician no-shows, and fulfillment breaks. After fulfillment, this operation can measure performance, which can be used to set up payment dashboards for sellers.

Request

Type	Name	Description	Schema
Path	`serviceJobId` required	A service job identifier. minLength : 1 maxLength : 100	string

Request example

GET https://sellingpartnerapi-na.amazon.com/service/v1/serviceJobs/jobId

Response

Name	Description	Schema
`createTime` optional	The date and time of the creation of the job in ISO 8601 format.	string (date-time)
`serviceJobId` optional	The service job identifier.	`ServiceJobId`
`serviceJobStatus` optional	The status of the service job.	enum (`ServiceJobStatus`)
`scopeOfWork` optional	The scope of work for the order.	`ScopeOfWork`
`seller` optional	Information about the seller of the service job.	`Seller`
`serviceJobProvider` optional	Information about the service job provider.	`ServiceJobProvider`
`preferredAppointmentTimes` optional	A list of appointment windows preferred by the buyer. Included only if the buyer selected appointment windows when creating the order.	< `AppointmentTime` > array
`appointments` optional	A list of appointments.	< `Appointment` > array
`serviceOrderId` optional	The Amazon-defined identifier for an order placed by the buyer in 3-7-7 format.	`OrderId`
`marketplaceId` optional	The marketplace identifier. Pattern : `"^[A-Z0-9]<li>$"`	string
`storeId` optional	The Amazon-defined identifier for the region scope. minLength : 1 maxLength : 100	string
`buyer` optional	Information about the buyer.	`Buyer`
`associatedItems` optional	A list of items associated with the service job.	< `AssociatedItem` > array
`serviceLocation` optional	Information about the location of the service job.	`ServiceLocation`

Response example for an active job with no appointment and customer preferred appointment times

{
  "payload": {
    "createTime": "2020-01-29T06:38:56.960Z",
    "serviceJobId": "jobIdExample",
    "serviceJobStatus": "PENDING_SCHEDULE",
    "scopeOfWork": {
      "asin": "ASINExample",
      "title": "titleExample",
      "quantity": 1,
      "requiredSkills": [
        "skillExample"
      ]
    },
    "seller": {
      "sellerId": "sellerIdExample"
    },
    "serviceProvider": {
      "serviceProviderId": "serviceProviderIdExample"
    },
    "preferredAppointmentTimes": [
      {
        "startTime": "2020-01-31T06:38:56.961Z",
        "durationInMinutes": 60
      }
    ],
    "serviceOrderId": "serviceOrderIdExample",
    "marketplaceId": "marketplaceIdExample",
    "storeId": "storeIdExample",
    "buyer": {
      "buyerId": "buyerIdExample",
      "name": "buyerNameExample",
      "phone": "phoneNumberExample",
      "isPrimeMember": true
    },
    "serviceLocation": {
      "serviceLocationType": "IN_HOME",
      "address": {
        "name": "nameExample",
        "addressLine1": "addressLineExample",
        "city": "cityExample",
        "postalCode": "postalCodeExample"
      }
    },
    "associatedItems": [
      {
        "asin": "ASINExample",
        "title": "titleExample",
        "quantity": 1,
        "orderId": "orderIdExample",
        "itemStatus": "SHIPPED",
        "brandName": "brandNameExample"
      }
    ]
  }
}

Response example for an active job with active appointment

{
  "payload": {
    "createTime": "2020-01-29T06:38:56.960Z",
    "serviceJobId": "jobIdExample",
    "serviceJobStatus": "NOT_SERVICED",
    "scopeOfWork": {
      "asin": "ASINExample",
      "title": "titleExample",
      "quantity": 1,
      "requiredSkills": [
        "skillExample"
      ]
    },
    "seller": {
      "sellerId": "sellerIdExample"
    },
    "serviceProvider": {
      "serviceProviderId": "serviceProviderIdExample"
    },
    "preferredAppointmentTimes": [
      {
        "startTime": "2020-01-31T06:38:56.961Z",
        "durationInMinutes": 60
      }
    ],
    "appointments": [
      {
        "appointmentId": "appointmentIdExample",
        "appointmentStatus": "ACTIVE",
        "appointmentTime": {
          "startTime": "2020-01-31T06:38:56.961Z",
          "durationInMinutes": 60
        }
      }
    ],
    "serviceOrderId": "serviceOrderIdExample",
    "marketplaceId": "marketplaceIdExample",
    "storeId": "storeIdExample",
    "buyer": {
      "buyerId": "buyerIdExample",
      "name": "buyerNameExample",
      "phone": "phoneNumberExample",
      "isPrimeMember": true
    },
    "serviceLocation": {
      "serviceLocationType": "IN_HOME",
      "address": {
        "name": "nameExample",
        "addressLine1": "addressLineExample",
        "city": "cityExample",
        "postalCode": "postalCodeExample"
      }
    },
    "associatedItems": [
      {
        "asin": "ASINExample",
        "title": "titleExample",
        "quantity": 1,
        "orderId": "orderIdExample",
        "itemStatus": "SHIPPED",
        "brandName": "brandNameExample"
      }
    ]
  }
}

Response example for an active job with cancelled appointment

{
  "payload": {
    "createTime": "2020-01-29T06:38:56.960Z",
    "serviceJobId": "jobIdExample",
    "serviceJobStatus": "NOT_FULFILLABLE",
    "scopeOfWork": {
      "asin": "ASINExample",
      "title": "titleExample",
      "quantity": 1,
      "requiredSkills": [
        "skillExample"
      ]
    },
    "seller": {
      "sellerId": "sellerIdExample"
    },
    "serviceProvider": {
      "serviceProviderId": "serviceProviderIdExample"
    },
    "preferredAppointmentTimes": [
      {
        "startTime": "2020-01-31T06:38:56.961Z",
        "durationInMinutes": 60
      }
    ],
    "appointments": [
      {
        "appointmentId": "appointmentIdExample",
        "appointmentStatus": "CANCELLED",
        "appointmentTime": {
          "startTime": "2020-01-31T06:38:56.961Z",
          "durationInMinutes": 60
        }
      }
    ],
    "serviceOrderId": "serviceOrderIdExample",
    "marketplaceId": "marketplaceIdExample",
    "storeId": "storeIdExample",
    "buyer": {
      "buyerId": "buyerIdExample",
      "name": "buyerNameExample",
      "phone": "phoneNumberExample",
      "isPrimeMember": true
    },
    "serviceLocation": {
      "serviceLocationType": "IN_HOME",
      "address": {
        "name": "nameExample",
        "addressLine1": "addressLineExample",
        "city": "cityExample",
        "postalCode": "postalCodeExample"
      }
    },
    "associatedItems": [
      {
        "asin": "ASINExample",
        "title": "titleExample",
        "quantity": 1,
        "orderId": "orderIdExample",
        "itemStatus": "SHIPPED",
        "brandName": "brandNameExample"
      }
    ]
  }
}

Tutorial: Get service job appointment slots

Learn how to retrieve:

Current appointment availability, as determined by the Scheduling Widget presentation configurations
Available resource capacity
Existing jobs

To retrieve information about service job appointment slots, call the following operations:

getAppointmentSlots returns slots based on a service identifier (such as an ASIN) and the region ID (such as a storeID) for which service is offered by the seller.
getAppointmmentSlotsByJobId returns slots for the service associated with the job that the seller has received for fulfillment.

You can use the available appointments you receive as inputs for the addAppointmentForServiceJobByServiceJobId and rescheduleAppointmentForServiceJobByServiceJobId operations, and for analytics.

📘
Note
When you use available slots as operation inputs, the calls might fail because of availability changes that can occur after you receive availability.

Prerequisites

To complete this tutorial, you need:

Authorization from the seller for whom you are making calls. Refer to Authorizing Selling Partner Applications for more information.
The Professional Services role.
An ASIN that the service provider configures for fulfillment.
A Store ID for a store or coverage area where the provider can fulfill orders.
Time slots available for the ASIN and Store ID.

Get appointment slots by ASIN and store ID

The getAppointmentSlots operation returns the appointment slots associated with the scope of work, defined by an ASIN and the storeId that represents a region. The capacity of a slot represents the number of appointments you can reserve in the slot at the time you call the operation.

Request

Type	Name	Description	Schema
Query	`asin` required	ASIN associated with the service.	string
Query	`storeId` required	Store identifier defining the region scope to retrieve appointment slots. minLength : 1 maxLength : 100	string
Query	`marketplaceIds` required	An identifier for the marketplace for which appointment slots are queried Max count : 1	< string > array
Query	`startTime` optional	A time from which the appointment slots are retrieved. The specified time must be in ISO 8601 format. If `startTime` is provided, `endTime` should also be provided. Default value is as per business configuration.	string
Query	`endTime` optional	A time up to which the appointment slots are retrieved. The specified time must be in ISO 8601 format. If `endTime` is provided, `startTime` should also be provided. Default value is as per business configuration. Maximum range of appointment slots can be 90 days.	string

Request example

GET http://sandbox.sellingpartnerapi-na.amazon.com/service/v1/appointmentSlots?asin=BBSPJ6789M&storeId=a5161d91-cb32-4e45-9394&startTime=2021-04-04T00:00:00Z&endTime=2021-04-04T00:03:00Z&marketplaceIds=ATVPDKIKX0DER

Response

Name	Description	Schema
`schedulingType` optional	Defines the type of slots.	enum (`SchedulingType`)
`startTime` optional	Start Time from which the appointment slots are generated in ISO 8601 format.	string (date-time)
`endTime` optional	End Time up to which the appointment slots are generated in ISO 8601 format.	string (date-time)
`appointmentSlots` optional	A list of time windows along with associated capacity in which the service can be performed.	< `AppointmentSlot` > array

Response example

{
  "payload": {
    "schedulingType": "REAL_TIME_SCHEDULING",
    "startTime": "2021-04-04T00:00:00Z",
    "endTime": "2021-04-04T02:00:00Z",
    "appointmentSlots": [
      {
        "startTime": "2021-04-04T00:00:00Z",
        "endTime": "2021-04-04T01:0:00Z",
        "capacity": 20
      },
      {
        "startTime": "2021-04-04T01:00:00Z",
        "endTime": "2021-04-04T02:0:00Z",
        "capacity": 0
      }
    ]
  }
}

Get appointment slots by service job ID

The getAppointmmentSlotsByJobId operation returns the appointment slots for the scope of work, defined by a job ID and marketplace IDs. The response format is same as that of getAppointmentSlots.

Request

Type	Name	Description	Schema
Path	`serviceJobId` required	A service job identifier to retrieve appointment slots for associated service. minLength : 1 maxLength : 100	string
Query	`marketplaceIds` required	An identifier for the marketplace in which the resource operates. Max count : 1	< string > array
Query	`startTime` optional	A time from which the appointment slots are retrieved. The specified time must be in ISO 8601 format. If `startTime` is provided, `endTime` should also be provided. Default value is as per business configuration.	string
Query	`endTime` optional	A time up to which the appointment slots are retrieved. The specified time must be in ISO 8601 format. If `endTime` is provided, `startTime` should also be provided. Default value is as per business configuration. Maximum range of appointment slots can be 90 days.	string

Request example

GET http://sandbox.sellingpartnerapi-na.amazon.com/service/v1/jobs/{jobId}/appointmentSlots?startTime=2021-04-04T00:00:00Z&endTime=2021-04-04T00:03:00Z&marketplaceIds=ATVPDKIKX0DER

Response

Name	Description	Schema
`schedulingType` optional	Defines the type of slots.	enum (`SchedulingType`)
`startTime` optional	Start Time from which the appointment slots are generated in ISO 8601 format.	string (date-time)
`endTime` optional	End Time up to which the appointment slots are generated in ISO 8601 format.	string (date-time)
`appointmentSlots` optional	A list of time windows along with associated capacity in which the service can be performed.	< `AppointmentSlot` > array

Response example for a successful reschedule

{
  "payload": {
    "schedulingType": "REAL_TIME_SCHEDULING",
    "startTime": "2021-04-04T00:00:00Z",
    "endTime": "2021-04-04T02:00:00Z",
    "appointmentSlots": [
      {
        "startTime": "2021-04-04T00:00:00Z",
        "endTime": "2021-04-04T01:0:00Z",
        "capacity": 20
      },
      {
        "startTime": "2021-04-04T01:00:00Z",
        "endTime": "2021-04-04T02:0:00Z",
        "capacity": 0
      }
    ]
  }
}

Tutorial: Setting service job appointments and assigning appointment resources

Learn how to add or reschedule appointments for service jobs, and assign appointment resources.

Reschedule appointments for service jobs and assign appointment resources with the following operations:

These operations confirm appointment preferences or add an initial appointment to any other valid start time in the future. Service sellers can reschedule an appointment to another valid start time in the future along with a reschedule reason.

Prerequisites

To complete this tutorial, you need:

Authorization from the seller for whom you are making calls. Refer to Authorizing Selling Partner Applications for more information.
A service job identifier assigned to the service provider. Only jobs assigned to the service provider can be accessed.
A future-dated appointment start time pre-configured in Amazon Systems for the service provider.

Add appointment for service job by service job ID

The addAppointmentForServiceJobByServiceJobId operation confirms an initial appointment preference or sets an initial appointment.

Request

Type	Name	Description	Schema
Path	`serviceJobId` required	An Amazon defined service job identifier. minLength : 1 maxLength : 100	string
Body	`body` required	Add appointment operation input details.	`AddAppointmentRequest`

Request example

POST https://sellingpartnerapi-na.amazon.com/service/v1/serviceJobs/00ba5b3b-3f3b-8e56-2cfc-6528e69cb519/appointments
{
  "appointmentTime": {
    "startTime": "2020-09-18T08:00:00.000Z",
    "durationInMinutes": 180
  }
}

📘
Note

You can only add appoinments in available future-date appointment slots (startTime + duration) that are pre-configured in Amazon Systems.

If durationInMinutes is not provided, then the pre-configured service duration is picked automatically.

If durationInMinutes is provided, then it should match the pre-configured appointment duration in Amazon Systems.

Response

Name	Description	Schema
`appointmentId`	New appointment identifier generated during the `addAppointmentForServiceJobByServiceJobId` or `rescheduleAppointmentForServiceJobByServiceJobId` operations.	`AppointmentId`
`warnings`	Warnings generated during the `addAppointmentForServiceJobByServiceJobId` or `rescheduleAppointmentForServiceJobByServiceJobId` operations.	`WarningList`
`errors`	Errors occurred during the `addAppointmentForServiceJobByServiceJobId` or `rescheduleAppointmentForServiceJobByServiceJobId` operations.	`ErrorList`

Response example

{
  "appointmentId": "00ba5b3b-3f3b-8e56-2cfc-6528e69cb519_e4ba6c15-ba0d-1812-41e4-9b1d4bff4e46"
}

Reschedule an appointment by service job ID

The rescheduleAppointmentForServiceJobByServiceJobId operation reschedules a service job appointment and provides a reason for rescheduling.

Request

Type	Name	Description	Schema
Path	`serviceJobId` required	An Amazon defined service job identifier. minLength : 1 maxLength : 100	string
Path	`appointmentId` required	An existing appointment identifier for the Service Job. minLength : 1 maxLength : 100	string
Body	`body` required	Reschedule appointment operation input details.	`RescheduleAppointmentRequest`

Reschedule reason codes by marketplace

Reason code	Reason description	Default	Heavy bulk	Recurring
RS1	Customer requested	-	DE	-
RS2	Product will not be delivered in time	-	DE	-
RS3	Need follow-up visit	-	DE	-
RS4	Provider cannot meet original appointment	US, AE, JP	US, DE, JP	US, JP
RS5	Product incompatible or broken	-	DE	-
RS6	Work is different than scoped	US, IN, UK, DE, AE, JP	US, IN, UK, JP	-
RS7	Code not in use	-	-	-
RS8	No longer works with customer schedule	UK, DE	US, UK, JP	US, JP
RS9	Problem with Amazon product or its delivery	US, IN, UK, DE, AE, JP	US, IN, UK, JP	-
RS10	Problem with non-Amazon product, delivery, or service	US, UK, DE, AE, JP	US, UK, JP	-
RS11	Customer didn't show up	US, IN, UK, DE, AE, JP	US, IN, UK, JP	US, JP
RS12	Provider cannot meet original appointment	IN, UK, DE	IN, UK	-
DRS1	Unable to access location	-	US, JP	-
DRS2	Customer requested a future date	-	US, JP	-
DRS3	Customer declined	-	US, JP	-
DRS4	Delivery will be too late	-	US, JP	-
DRS5	Can't find access	-	US, JP	-
DRS6	Business closed	-	US, JP	-
SRS1	Customer requested cancellation	-	US, JP	-

Request example

POST https://sellingpartnerapi-na.amazon.com/service/v1/serviceJobs/eeba5b3c-5325-a6e0-5bfc-889b8a392fcf/appointments/eeba5b3c-5325-a6e0-5bfc-889b8a392fcf_68ba5b4a-07b8-bcb3-e6e9-e84b34462c56
{
  "appointmentTime": {
    "startTime": "2020-09-18T08:00:00.000Z",
    "durationInMinutes": 180
  },
  "rescheduleReasonCode": "RS4"
}

Response

Name	Description	Schema
`appointmentId`	New appointment identifier generated during the `addAppointmentForServiceJobByServiceJobId` or `rescheduleAppointmentForServiceJobByServiceJobId` operations.	`AppointmentId`
`warnings`	Warnings generated during the `addAppointmentForServiceJobByServiceJobId` or `rescheduleAppointmentForServiceJobByServiceJobId` operations.	`WarningList`
`errors`	Errors occurred during the `addAppointmentForServiceJobByServiceJobId` or `rescheduleAppointmentForServiceJobByServiceJobId` operations.	`ErrorList`

📘
Note
The RESOURCES_UNASSIGNED warning provides details of preassigned resources to the appointment that do not have an assignment. The service provider should assign new resources to the rescheduled appointment.

Response example

{
  "appointmentId": "eeba5b3c-5325-a6e0-5bfc-889b8a392fcf_68ba5b4a-07b8-bcb3-e6e9-e84b34462c56",
  "warnings": [
    {
      "code": "RESOURCES_UNASSIGNED",
      "message": "Unassigned resources: resourceId1,resourceId2"
    }
  ]
}

Add new resources to a service job appointment

The assignAppointmentResources operation assigns or updates resources in appointments for their service orders. This operation performs resource validations against a number of criteria, such as skills, available capacity, and coverage area inclusions, before setting an appointment resource assignment.

Request

Type	Name	Description	Schema
Path	`serviceJobId` required	An Amazon-defined service job identifier. Get this value by calling the `getServiceJobs` operation of the Services API. minLength : 1 maxLength : 100	string
Path	`appointmentId` required	An Amazon-defined identifier of active service job appointment. minLength : 1 maxLength : 100	string
Body	`body` required	Request schema for the `assignAppointmentResources` operation.	`AssignAppointmentResourcesRequest`

Request example

PUT https://marketplaceapi.amazonservices.com/service/v1/serviceJobs/09ba5b3b-ha3b-8d56-2cfc-6524s68cb519/appointments/09ba5b3b-ha3b-8d56-2cfc-6524s68cb519_87bb1ssd-bd17-1e20-36d9-c4e0bsfb1s51/resources
{
  "resources": [
    {
      "resourceId": "<resourceId>"
    },
      ...
  ]
}

Response

Name	Description	Schema
warnings optional	Warnings generated during the `assignAppointmentResources` operation.	`WarningList`

Response example

{}

Tutorial: Closing service jobs

Learn how to set fulfillment data, such as:

Start and end date-times
Fulfillment resources
Fulfillment documents such as Proof Of Appointment (POA) files
Job status, such as completed or cancelled

To set a job as complete, use the following operations:

setAppointmentFulfillmentData sets data such as fulfillment date-times, resources, and fulfillment document identifiers.
createServiceDocumentUploadDestination creates an upload destination for fulfillment documents such as Proof Of Appointment (POA) files.
completeServiceJobByServiceJobId sets a service job as completed.
cancelServiceJobByServiceJobId sets a service job as cancelled.

Before you set a job as complete, you must provide appointment fulfillment data, using setAppointmentFulfillmentData and createServiceDocumentUploadDestination. There are three types of fulfillment data:

Appointment Fulfillment Times: The actual fulfillment date-time start and end.
Appointment Fulfillment Resources: The actual resources that fulfilled an appointment.
Appointment Fulfillment Documents: Documents that:
- Serve as evidence of service completion
- Were used in the course of fulfillment
- Record aspects of fulfillment

📘
Note
The Amazon business line and service sellers determine the minimum requirements for fulfillment data and documents to close a job. Service sellers should confer with their relevant Amazon business line partners to settle appropriate API usage before they integrate with the Services API.

Prerequisites

To complete this tutorial, you need:

Authorization from the seller for whom you are making calls. Refer to Authorizing Selling Partner Applications for more information.
A service job identifier assigned to the service provider. Only jobs assigned to the service provider can be accessed. Job status are verified as in NotServiced state.
A scheduled appointment identifier pre-configured in Amazon Systems for the service provider.
An active appointment.

Step 1. Set or update service appointment fulfillment data

The setAppointmentFulfillmentData operation updates multiple aspects of service job appointment fulfillment data that you must record before you set a job as complete.

Request

Type	Name	Description	Schema
Path	`serviceJobId` required	An Amazon-defined service job identifier. Get this value by calling the `getServiceJobs` operation of the Services API. minLength : 1 maxLength : 100	string
Path	`appointmentId` required	An Amazon-defined identifier of active service job appointment. minLength : 1 maxLength : 100	string
Body	`body` required	Appointment fulfillment data collection details.	`SetAppointmentFulfillmentDataRequest`

Request example

PUT https://sellingpartnerapi-na.amazon.com/service/v1/serviceJobs/5eb7e419-134d-63c4-c5be-f082dc5d91c6/appointments/5eb7e419-134d-63c4-c5be-f082dc5d91c6_94ba8164-ac2c-3434-3c34-5b287aa8f7b5/fulfillment
{
  "fulfillmentTime": {
    "startTime": "2020-01-02T13:18:10.668Z",
    "endTime": "2022-01-03T13:18:10.668Z"
  }
}

Response

A successful request returns an empty response.

Response example

{}

Step 2. Upload a fulfillment document

The createServiceDocumentUploadDestination operation creates a storage destination and identifier for a fulfillment document. This document is necessary to set a job as complete.

To upload a document:

Create an upload destination for the service document with the createServiceDocumentUploadDestination operation.
Encrypt and upload the file.

Request

Type	Name	Description	Schema
Body	`body` required	Upload document operation input details.	`ServiceUploadDocument`

Request example

POST https://sellingpartnerapi-na.amazon.com/services/v1/documents
{
  "contentType": "PNG",
  "contentLength": 1386437,
  "contentMD5": "97WrSKv9ffHkDopCdB32mw=="
}

Response

Name	Description	Schema
`uploadDestinationId`	The unique identifier to be used by APIs that reference the upload destination.	string
`url`	The URL to which to upload the file.	string
`encryptionDetails`	Encryption details for required client-side encryption and decryption of document contents.	`EncryptionDetails`
`headers`	The headers to include in the upload request.	object

Response example

{
  "encryptionDetails": {
    "standard": "AES",
    "initializationVector": "paPlpo1iBBLmyOhU0mIo5g==",
    "key": "PDuDJm2l+0ydObrRpS48tB+t2qbtOmWhSEOiFWKnH2k="
  },
  "uploadDestinationId": "amzn1.tortuga.3.15ba627d-8e24-42ad-89d1-5eb01f5ba0af.T15MXQRST78UTC<->amzn1.tortuga.1.token.DizquVc+EoX/lWAV/7WTlw==",
  "url": "https://tortuga-devo.s3-us-west-2.amazonaws.com/%2FThirtyDays/amzn1.tortuga.3.15ba627d-8e24-42ad-89d1-5eb01f5ba0af.T15MXQRST78UTC?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210108T103450Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=300&X-Amz-Credential=AKIAUR3X5C6O5CADVWED%2F20210108%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=dd2fefe6c6102aba14bab1481b33cf07dcc0385bd49f7eb5796d77b082ea5ba3"
}

Use the information the response provides to encrypt and upload the file.

The following Java sample encrypts and uploads a feed. This sample code uses the Apache HTTP client.

Use the following as input for the sample code:
a. Your file content as the argument for the stream parameter of the InputStream method of the UploadToDestinationExample class.
b. The initializationVector and key values from the createServiceDocumentUploadDestination response as arguments for the iv and key parameters of the EncryptionDetails method of the EncryptionDetails class.
c. The url value from the createServiceDocumentUploadDestination response as the argument for the url parameter of the uploadToDestination method of the UploadToDestinationExample class.
Save the sha256sum value to pass as the ContentSha256 parameter in setAppointmentFulfillmentData.

package com.amazon.spapi;

import org.apache.commons.io.IOUtils;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.InputStreamEntity;
import org.apache.http.impl.client.HttpClients;
import javax.crypto.Cipher;
import javax.crypto.CipherInputStream;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.io.IOException;
import java.io.InputStream;
import java.security.DigestInputStream;
import java.security.GeneralSecurityException;
import java.security.Key;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Base64;

public class UploadToDestinationExample {
    static final String SHA_256 = "SHA-256";
    static final String AES = "AES";
    static final int AES_BLOCK_SIZE = 16;
    static final Base64.Encoder BASE64_ENCODER = Base64.getEncoder();
    static final Base64.Decoder BASE64_DECODER = Base64.getDecoder();
    static final CryptoProvider AES_CRYPTO_PROVIDER = UploadToDestinationExample::getInitializedCipher;

    static InputStream buildCipherInputStream(EncryptionDetails encryptionDetails, InputStream stream, int mode) {
        return new CipherInputStream(stream,
            AES_CRYPTO_PROVIDER.getInitializedCipher(mode, encryptionDetails));
    }

    private static InputStream buildCipherInputStream(EncryptionDetails encryptionDetails, InputStream stream) {
        return buildCipherInputStream(encryptionDetails, stream, Cipher.ENCRYPT_MODE);
    }

    static Cipher getInitializedCipher(int mode, EncryptionDetails details) {
        Cipher cipher;
        try {
            cipher = Cipher.getInstance(AES);
            Key key = new SecretKeySpec(BASE64_DECODER.decode(details.getKey()), AES);
            byte[] iv = BASE64_DECODER.decode(details.getIv());
            IvParameterSpec ivParameterSpec = new IvParameterSpec(iv);
            cipher.init(mode, key, ivParameterSpec, new SecureRandom());
        } catch (GeneralSecurityException e) {
            throw new IllegalStateException("Could not create Cipher for key-iv pair", e);
        }
        return cipher;
    }

    UploadDetails uploadToDestination(EncryptionDetails encryptionDetails, String uploadDestinationId, String url,
        String contentType,
        long documentLength,
        InputStream inputStream) {
        try {
            inputStream = buildCipherInputStream(encryptionDetails, inputStream);
            DigestInputStream sha256sumStream = new DigestInputStream(inputStream, MessageDigest.getInstance(SHA_256));
            inputStream = sha256sumStream;
            // Put the file
            HttpClient httpClient = HttpClients.createDefault();
            HttpPut httpPut = new HttpPut(url);
            // This content length calculation is specific to AES
            long contentLength = (documentLength / AES_BLOCK_SIZE + 1) *
                AES_BLOCK_SIZE;
            // This sets the Content-Length header since we specified the contentLength
            HttpEntity document = new InputStreamEntity(inputStream,
                contentLength);
            httpPut.setHeader("Content-Type", contentType);
            httpPut.setEntity(document);
            //Put the content in the S3 Pre-signed URL
            HttpResponse httpResponse = httpClient.execute(httpPut);
            if (httpResponse == null ||
                (httpResponse.getStatusLine().getStatusCode() / 100) != 2) {
                // Handle error responses here.
                throw new IllegalStateException("Could not upload to S3.");
            }
            // Document was successfully uploaded!
            byte[] sha256sumDigest = sha256sumStream.getMessageDigest().digest();
            String sha256sum = BASE64_ENCODER.encodeToString(sha256sumDigest);
            return new UploadDetails(uploadDestinationId, sha256sum);
        } catch (IOException | NoSuchAlgorithmException e) {
            throw new RuntimeException("Error occurred when attempting to encrypt or upload to S3.", e);
        } finally {
            IOUtils.closeQuietly(inputStream);
        }
    }
}

Step 3. Complete a service job

The completeServiceJobByServiceJobId operation marks a service job as complete. If the given job is the only active job in the order, then it marks the entire order as complete.

Request

Type	Name	Description	Schema
Path	`serviceJobId` required	An Amazon defined service job identifier. minLength : 1 maxLength : 100	string

Request example

PUT https://sellingpartnerapi-na.amazon.com/service/v1/serviceJobs/09ba5b3b-ha3b-8d56-2cfc-6524s68cb519/completions

Response

A successful request returns an empty response.

Response example

{}

Step 4. Cancel a service job

The cancelServiceJobByServiceJobId operation marks a service job as cancelled. If the given job is the only active job in the order, then it marks the entire order as cancelled.

Request

Type	Name	Description	Schema
Path	`serviceJobId` required	An Amazon defined service job identifier. minLength : 1 maxLength : 100	string
Query	`cancellationReasonCode` required	A cancel reason code that specifies the reason for cancelling a service job. minLength : 1 maxLength : 100	string

Cancellation reason codes by marketplace

Reason code	Reason description	Default	Heavy bulk
S1	Customer didn't show up.	US, IN, UK, DE	US, IN, UK, DE
S2	Customer outside service area.	-	DE
S3	Work is different than scoped and order cannot be completed.	US, IN, UK, DE	US, IN, UK, DE
S4	Provider unable to contact customer.	-	DE
S5	Provider cannot meet customer's schedule.	-	DE
S6	Job requires professional trade license.	-	DE
S7 - S12	Codes not in use.	-	-
S13	Provider cannot meet original appointment.	US, IN, UK, DE	US, IN, UK
S14	Provider cannot meet new appointment request.	US	US
S15	Problem with Amazon product or its delivery.	US, IN, UK, DE	US, IN, UK
S16	Problem with non-Amazon product, delivery, or service.	US, UK, DE	US, UK
S17	I don't need this service.	US, IN	US, IN
S18 - S19	Codes not in use.	-	-
S20	Too expensive.	IN	IN
S21 - S26	Codes not in use.	-	-
S27	Brand installed.	IN	IN
S28	Coverage area changed.	-	-
S29	Pricing mistake.	-	-
S30	No longer works with customer schedule.	-	-
S31	Product damaged.	IN	-
S32	Risky site.	IN	-
S33	Customer wants cancellation.	IN	-
S34	Site not ready.	IN	-
S35	Product not delivered.	IN	-
S36	Additional material needed.	IN	-
S37	Customer wants reschedule.	IN	-
S38	Product returned.	IN	-
S39	We could not reach you.	IN	-
S40	Service already completed.	IN	-
S41	Service in another location.	IN	-
S42	Needs revisit.	IN	-
S43	Documents not available.	IN	-
S44	Slot missed.	IN	-
S45	Parts not available.	IN	-
S46	Wrong completion.	IN	-
S47	Need customer approval for repair.	IN	-
S48 - S50	Codes not in use.	-	-
S51	Installation done by third party and customer does not require installation.	IN	-
S52	Product damaged, non-installable product, customer returned the product, or product gifted.	IN	-
S53 - S54	Codes not in use.	-	-
S55	Restriction on visit.	IN	-

Select a cancellation reason code

Call the getServiceJobByServiceJobId operation and check for the marketplaceId value to identify the marketplace details associated with the service order of a job.
Call the getServiceJobByServiceJobId operation and check for the serviceType value to identify the service type of the job.
- If serviceType is heavybulky, then search for a reason code in the Heavy Bulky column.
- Otherwise, search for a reason code in the Default column.
Select a reason code suitable for your use case and pass it as a query parameter when you request a job for cancellation.

Request example

PUT https://sellingpartnerapi-na.amazon.com/service/v1/serviceJobs/09ba5b3b-ha3b-8d56-2cfc-6524s68cb519/cancellations?cancellationReasonCode=S1

Response

A successful request returns an empty response.

Response example

{}

Tutorial: Manage resource capacity schedules and reservations

You can use the Services API to manage service resource capacity schedules and support appointment availability and reservations that exclude scheduled capacity from appointment availability.

Capacity management operations eliminate manual integration and operation processes related to resource capacity. With these operations, you can provide the availability of a resource in real time. Schedule provides a resource’s availability. Reservation provides a resources's unavailability.

updateSchedule is used to create or update resource capacity schedules that make capacity available for service job appointments.
createReservation is used to block out portions of scheduled resource capacity from being available for service job appointments.
updateReservation is used to update reservations in order to account the need to shift existing block outs on resource capacity schedules.
cancelReservation is used to remove reservations no longer needed to block portions of resource capacity schedules.

Prerequisites

To complete this tutorial, you need:

Authorization from the seller for whom you are making calls. Refer to Authorizing Selling Partner Applications for more information.

Update a resource schedule

The updateSchedule operation creates or updates resource capacity schedules, which are the basis for capacity-driven appointment scheduling.

updateSchedule overwrites the resource’s existing schedule, so you can use it to provide a resource’s schedule for the first time and for subsequent changes. The schedule continues to be valid until the endTime, or recurrence’s endTime if you provide recurrence. The minimum slot duration is five minutes for US marketplaces and 30 mins for UK and DE marketplaces. There is no way to clear the schedule of a resource; providing an empty schedule is considered an invalid request.

Request

Type	Name	Description	Schema
Path	`resourceId` required	Resource (store) Identifier minLength : 1 maxLength : 100	string
Body	`body` required	Schedule details	`UpdateScheduleRequest`
Query	`marketplaceIds` required	An identifier for the marketplace in which the resource operates. Max count : 1	< string > array

Request example

PUT https://sellingpartnerapi-na.amazon.com/service/v1/serviceResources/a6a5b26c-31cd-4b69-a168-63455f524923/schedules?marketplaceIds=ATVPDKIKX0DER
{
  "schedules": [
    {
      "startTime": "2020-01-01T10:00:00Z",
      "endTime": "2020-01-01T17:59:00Z",
      "capacity": 10,
      "recurrence": {
        "endTime": "2020-01-07T23:59:00Z",
        "daysOfWeek": [
          "MONDAY",
          "TUESDAY",
          "WEDNESDAY",
          "THURSDAY",
          "FRIDAY"
        ]
      }
    },
    {
      "startTime": "2020-01-11T00:00:00Z",
      "endTime": "2020-01-11T23:59:00Z"
    }
  ]
}

Response

A successful request returns an empty response.

Response example

{}

Create a reservation against a resource

The createReservation operation creates a reservation against a resource, which reduces available capacity for that time-frame.

For service reservations, the duration is standard and is Amazon-defined. Creating a reservation requires that the resource has the requested capacity available in that time frame. A walk-in appointment for a tire-change is an example of where createReservation can be used. If you want to assign resource R1 to this job, call the API with R1 as the resourceId, with start and end times of the job and APPOINTMENT as the type.

Request

Type	Name	Description	Schema
Body	`body` required	Reservation details	`CreateReservationRequest`
Query	`marketplaceIds` required	An identifier for the marketplace in which the resource operates. Max count : 1	< string > array

Request example

POST https://sellingpartnerapi-na.amazon.com/service/v1/reservation?marketplaceIds=ATVPDKIKX0DER
{
  "resourceId": "a6a5b26c-31cd-4b69-a168-63455f524923",
  "reservation": {
    "availabilityRecord": {
      "startTime": "2020-04-01T10:00:00Z",
      "endTime": "2020-04-01T11:00:00Z"
    },
    "type": "Time-off",
    "notes": "Lunch break"
  }
}

Response

Name	Description	Schema
`reservation` optional	Reservation record if the operation failed. It only contains the new `reservationId` if the operation is successful.	`Reservation`
`warnings` optional	Warnings encountered, if any.	`WarningList`
`errors` optional	Errors encountered, if any.	`ErrorList`

Response example

{
  "payload": {
    "reservation": {
      "reservationId": "217047ab-9c45-4558-a844-8c36346d2d2d"
    }
  }
}

Update an existing resource reservation

The updateReservation operation updates a reservation against a resource, reducing available capacity for that time-frame.

This operation can reschedule a reservation. No other fields can be changed except the start-times and end-times of the reservation. This operation succeeds only if there is sufficient capacity of the resource available at the new time frame. The response contains the reservationId of the reservation you update.

Request

Type	Name	Description	Schema
Path	`reservationId` required	Reservation Identifier minLength : 1 maxLength : 100	string
Body	`body` required	Reservation details	`UpdateReservationRequest`
Query	`marketplaceIds` required	An identifier for the marketplace in which the resource operates. Max count : 1	< string > array

Request example

PUT https://sellingpartnerapi-na.amazon.com/service/v1/reservation/99a6df2d-b4c2-4e4b-8f36-91a69543ee68?marketplaceIds=ATVPDKIKX0DER
{
  "resourceId": "a6a5b26c-31cd-4b69-a168-63455f524923",
  "reservation": {
    "availability": {
      "startTime": "2020-04-01T10:00:00Z",
      "endTime": "2020-04-01T11:00:00Z"
    }
  }
}

Response

Name	Description	Schema
`reservation`	Reservation record if the operation failed. It only contains the new `reservationId` if the operation is successful.	`Reservation`
`warnings`	Warnings encountered, if any.	`WarningList`
`errors`	Errors encountered, if any.	`ErrorList`

Response example

{
  "payload": {
    "reservation": {
      "reservationId": "8482e697-36d8-4ae8-8380-cb08d0ed46ca"
    }
  }
}

📘
Note
A successful call returns a new reservationID that can be used to make further changes to this reservation. The previous reservationId can be discarded.

Cancel a reservation

The cancelReservation operation cancels a reservation. Cancelling a reservation creates capacity for available appointment opportunities.

Request

Type	Name	Description	Schema
Path	`reservationId` required	Reservation Identifier minLength : 1 maxLength : 100	string
Query	`marketplaceIds` required	An identifier for the marketplace in which the resource operates. Max count : 1	< string > array

Request example

DELETE https://sellingpartnerapi-na.amazon.com/service/v1/reservation/99a6df2d-b4c2-4e4b-8f36-91a69543ee68?marketplaceIds=ATVPDKIKX0DER

Response

A successful request returns an empty response.

Response example

{}

📘
Note
A successful call returns a new reservationID that can be used to make further changes to this reservation. The previous reservationId can be discarded.

Updated about 1 month ago

What is the Services API?

Operations in the Services API

Selling Partner API roles

Tutorial: Getting Service Job data

Prerequisites

Step 1. Get all jobs created or updated during a time frame that you specify

Parameters

Request example

Response

Response example for an active job with no appointment

Response example for active jobs with active appointments

Response example for a cancelled job status

Step 2. Get service job details

Request

Request example

Response

Response example for an active job with no appointment and customer preferred appointment times

Response example for an active job with active appointment

Response example for an active job with cancelled appointment

Tutorial: Get service job appointment slots

📘Note

Prerequisites

Get appointment slots by ASIN and store ID

Request

Request example

Response

Response example

Get appointment slots by service job ID

Request

Request example

Response

Response example for a successful reschedule

Tutorial: Setting service job appointments and assigning appointment resources

Prerequisites

Add appointment for service job by service job ID

Request

Request example

📘Note

Response

Response example

Reschedule an appointment by service job ID

Request

Reschedule reason codes by marketplace

Request example

Response

📘Note

Response example

Add new resources to a service job appointment

Request

Request example

Response

Response example

Tutorial: Closing service jobs

📘Note

Prerequisites

Step 1. Set or update service appointment fulfillment data

Request

Request example

Response

Response example

Step 2. Upload a fulfillment document

Request

Request example

Response

Response example

Step 3. Complete a service job

Request

Request example

Response

Response example

Step 4. Cancel a service job

Request

Cancellation reason codes by marketplace

Select a cancellation reason code

Request example

Response

Response example

Tutorial: Manage resource capacity schedules and reservations

Prerequisites

Update a resource schedule

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note