@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Order API
@base https://apix.ebay.com/buy/order/v2
@version v2.1.2
@auth OAuth2
@common_fields {X-EBAY-C-MARKETPLACE-ID: str # This header identifies the eBay marketplace where the order will occur. Note:  For this method, this value must match the X-EBAY-C-MARKETPLACE-ID used when the associated checkout session was created.See HTTP request headers for the marketplace ID values., X-EBAY-C-ENDUSERCTX: str # This header is used to specify the deviceId for the device/user attempting to make the call.It contains an alphanumeric string that allows a payment gateway to track an API call attempt and confirm that it is a verified payment attempt by a device/user.}
@endpoints 8
@toc guest_checkout_session(7), guest_purchase_order(1)

@group guest_checkout_session
@endpoint POST /guest_checkout_session/{checkoutSessionId}/apply_coupon
@desc Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.Important! ">Important! (Limited Release) This method is only available to select developers approved by business units.This method adds a coupon to an eBay guest checkout session and applies it to all the eligible items in the order.The checkoutSessionId is passed in as a URI parameter and is required. The redemption code of the coupon is in the payload and is also required.For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
@required {checkoutSessionId: str # This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.This value is returned by the initiateGuestCheckoutSession method.Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details., Content-Type: str # This header indicates the format of the request body provided by the client. Its value should be set to application/json.  For more information, refer to HTTP request headers.}
@optional {redemptionCode: str # The redemption code of the coupon.Maximum: One redemption code per order}
@returns(200) {appliedCoupons: [map], checkoutSessionId: str, lineItems: [map], pricingSummary: map{additionalSavings: map{currency: str, value: str}, adjustment: map{amount: map{currency: str, value: str}, label: str}, deliveryCost: map{currency: str, value: str}, fee: map{currency: str, value: str}, importCharges: map{amount: map{currency: str, value: str}, applicableChargeType: str}, importTax: map{amount: map{currency: str, value: str}, importTaxType: str}, priceDiscount: map{currency: str, value: str}, priceSubtotal: map{currency: str, value: str}, tax: map{currency: str, value: str}, total: map{currency: str, value: str}}, shippingAddress: map{addressLine1: str, addressLine2: str, city: str, country: str, county: str, phoneNumber: str, postalCode: str, recipient: map{firstName: str, lastName: str}, stateOrProvince: str}, warnings: [map]} # OK
@errors {400: Bad Request, 403: Access Forbidden, 404: Resource Not Found, 409: Conflict, 500: Internal Server Error}

@endpoint GET /guest_checkout_session/{checkoutSessionId}
@desc Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.Important! ">Important! (Limited Release) This method is only available to select developers approved by business units.This method returns the details of the specified guest checkout session. The checkoutSessionId is passed in as a URI parameter and is required. This method has no request payload.For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
@required {checkoutSessionId: str # This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.This value is returned by the initiateGuestCheckoutSession method.Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details.}
@returns(200) {appliedCoupons: [map], checkoutSessionId: str, lineItems: [map], pricingSummary: map{additionalSavings: map{currency: str, value: str}, adjustment: map{amount: map{currency: str, value: str}, label: str}, deliveryCost: map{currency: str, value: str}, fee: map{currency: str, value: str}, importCharges: map{amount: map{currency: str, value: str}, applicableChargeType: str}, importTax: map{amount: map{currency: str, value: str}, importTaxType: str}, priceDiscount: map{currency: str, value: str}, priceSubtotal: map{currency: str, value: str}, tax: map{currency: str, value: str}, total: map{currency: str, value: str}}, shippingAddress: map{addressLine1: str, addressLine2: str, city: str, country: str, county: str, phoneNumber: str, postalCode: str, recipient: map{firstName: str, lastName: str}, stateOrProvince: str}, warnings: [map]} # OK
@errors {400: Bad Request, 403: Access Forbidden, 404: Resource Not Found, 409: Conflict, 500: Internal Server Error}

@endpoint POST /guest_checkout_session/initiate
@desc Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.Important! ">Important! (Limited Release) This method is only available to select developers approved by business units.This method creates an eBay guest checkout session, which is the first step in performing a checkout. The method returns a checkoutSessionId that you use as a URI parameter in subsequent guest checkout methods.  Note: This method also returns the X-EBAY-SECURITY-SIGNATURE response header, which is a token that is used to launch the Checkout with eBay widget. The Checkout with eBay widget allows eBay guests to pay for items without leaving your site. For details about the Checkout with eBay widget, see Integrating the Checkout with eBay button. Also see Negative Testing Using Stubs for information on how to emulate error conditions for this  method using stubs.TIP: To test the entire checkout flow, you might need a "test" credit card. You can generate a credit card number from http://www.getcreditcardnumbers.com.For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
@required {Content-Type: str # This header indicates the format of the request body provided by the client. Its value should be set to application/json.  For more information, refer to HTTP request headers.}
@optional {contactEmail: str # The buyer's email address., lineItemInputs: [map{itemId: str, quantity: int(int32)}] # An array used to define the line item(s) and desired quantity for an eBay guest checkout session.Maximum: 10 line items, shippingAddress: map{addressLine1: str, addressLine2: str, city: str, country: str, county: str, phoneNumber: str, postalCode: str, recipient: map, stateOrProvince: str} # A type that defines the fields for a shipping address. For restrictions, see Shipping restrictions.Note: If the address cannot be validated, a warning message will be returned.}
@returns(200) {appliedCoupons: [map], checkoutSessionId: str, lineItems: [map], pricingSummary: map{additionalSavings: map{currency: str, value: str}, adjustment: map{amount: map{currency: str, value: str}, label: str}, deliveryCost: map{currency: str, value: str}, fee: map{currency: str, value: str}, importCharges: map{amount: map{currency: str, value: str}, applicableChargeType: str}, importTax: map{amount: map{currency: str, value: str}, importTaxType: str}, priceDiscount: map{currency: str, value: str}, priceSubtotal: map{currency: str, value: str}, tax: map{currency: str, value: str}, total: map{currency: str, value: str}}, shippingAddress: map{addressLine1: str, addressLine2: str, city: str, country: str, county: str, phoneNumber: str, postalCode: str, recipient: map{firstName: str, lastName: str}, stateOrProvince: str}, warnings: [map]} # OK
@errors {400: Bad Request, 409: Conflict, 500: Internal Server Error}

@endpoint POST /guest_checkout_session/{checkoutSessionId}/remove_coupon
@desc Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.Important! ">Important! (Limited Release) This method is only available to select developers approved by business units.This method removes a coupon from an eBay guest checkout session. The checkoutSessionId is passed in as a URI parameter and is required. The redemption code of the coupon is specified in the payload and is also required.For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
@required {checkoutSessionId: str # This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.This value is returned by the initiateGuestCheckoutSession method.Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details., Content-Type: str # This header indicates the format of the request body provided by the client. Its value should be set to application/json.  For more information, refer to HTTP request headers.}
@optional {redemptionCode: str # The redemption code of the coupon.Maximum: One redemption code per order}
@returns(200) {appliedCoupons: [map], checkoutSessionId: str, lineItems: [map], pricingSummary: map{additionalSavings: map{currency: str, value: str}, adjustment: map{amount: map{currency: str, value: str}, label: str}, deliveryCost: map{currency: str, value: str}, fee: map{currency: str, value: str}, importCharges: map{amount: map{currency: str, value: str}, applicableChargeType: str}, importTax: map{amount: map{currency: str, value: str}, importTaxType: str}, priceDiscount: map{currency: str, value: str}, priceSubtotal: map{currency: str, value: str}, tax: map{currency: str, value: str}, total: map{currency: str, value: str}}, shippingAddress: map{addressLine1: str, addressLine2: str, city: str, country: str, county: str, phoneNumber: str, postalCode: str, recipient: map{firstName: str, lastName: str}, stateOrProvince: str}, warnings: [map]} # OK
@errors {400: Bad Request, 403: Access Forbidden, 404: Resource Not Found, 409: Conflict, 500: Internal Server Error}

@endpoint POST /guest_checkout_session/{checkoutSessionId}/update_quantity
@desc Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.Important! ">Important! (Limited Release) This method is only available to select developers approved by business units.This method changes the quantity of the specified line item in an eBay guest checkout session.For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
@required {checkoutSessionId: str # This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.This value is returned by the initiateGuestCheckoutSession method.Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details., Content-Type: str # This header indicates the format of the request body provided by the client. Its value should be set to application/json.  For more information, refer to HTTP request headers.}
@optional {lineItemId: str # A unique eBay-assigned ID value that identifies a line item in a purchase order.For example: v1|2**********6|5**********4 or v1|1**********9|0.For more information about item IDs for RESTful APIs, see Legacy API compatibility., quantity: int(int32) # The quantity of the line item that you wish to update.}
@returns(200) {appliedCoupons: [map], checkoutSessionId: str, lineItems: [map], pricingSummary: map{additionalSavings: map{currency: str, value: str}, adjustment: map{amount: map{currency: str, value: str}, label: str}, deliveryCost: map{currency: str, value: str}, fee: map{currency: str, value: str}, importCharges: map{amount: map{currency: str, value: str}, applicableChargeType: str}, importTax: map{amount: map{currency: str, value: str}, importTaxType: str}, priceDiscount: map{currency: str, value: str}, priceSubtotal: map{currency: str, value: str}, tax: map{currency: str, value: str}, total: map{currency: str, value: str}}, shippingAddress: map{addressLine1: str, addressLine2: str, city: str, country: str, county: str, phoneNumber: str, postalCode: str, recipient: map{firstName: str, lastName: str}, stateOrProvince: str}, warnings: [map]} # OK
@errors {400: Bad Request, 403: Access Forbidden, 404: Resource Not Found, 409: Conflict, 500: Internal Server Error}

@endpoint POST /guest_checkout_session/{checkoutSessionId}/update_shipping_address
@desc Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.Important! ">Important! (Limited Release) This method is only available to select developers approved by business units.This method changes the shipping address for the order in an eBay guest checkout session. All the line items in an order must be shipped to the same address, but the shipping method can be specific to the line item.Note: If the address submitted cannot be validated, a warning message will be returned. This does not prevent the method from executing, but you may want to verify the address.For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
@required {checkoutSessionId: str # This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.This value is returned by the initiateGuestCheckoutSession method.Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details., Content-Type: str # This header indicates the format of the request body provided by the client. Its value should be set to application/json.  For more information, refer to HTTP request headers.}
@optional {addressLine1: str # The first line of the street address where the item is being shipped.Maximum:40 characters for AU, CA, and US marketplaces35 characters for DE and GB marketplaces50 characters for all other marketplaces, addressLine2: str # The second line of the street address where the item is being shipped. This optional field can be used for information such as 'Suite Number' or 'Apt Number'.Maximum:40 characters for AU, CA, and US marketplaces35 characters for DE and GB marketplaces50 characters for all other marketplaces, city: str # The city of the address where the item is being shipped., country: str # The two letter code representing the country of the address. For implementation help, refer to eBay API documentation, county: str # The county of the address where the item is being shipped., phoneNumber: str # The phone number of the person receiving the package.Note: It is highly recommended that when entering the phone number you include the country code.For example, if a US phone number is 4********4, you would enter +14********4. If you do not include this code, the service will use the country specified in the country field.You can find the country code at https://countrycode.org., postalCode: str # The postal code of the address where the item is being shipped.Note: This is optional when shipping to EBAY_HK (Hong Kong)., recipient: map{firstName: str, lastName: str} # A container that defines the full name of the person receiving the purchase order., stateOrProvince: str # The state or province of the address.Note: For the US marketplace, this is a two-character value. For a list of valid values, see US State and Canada Province Codes.}
@returns(200) {appliedCoupons: [map], checkoutSessionId: str, lineItems: [map], pricingSummary: map{additionalSavings: map{currency: str, value: str}, adjustment: map{amount: map{currency: str, value: str}, label: str}, deliveryCost: map{currency: str, value: str}, fee: map{currency: str, value: str}, importCharges: map{amount: map{currency: str, value: str}, applicableChargeType: str}, importTax: map{amount: map{currency: str, value: str}, importTaxType: str}, priceDiscount: map{currency: str, value: str}, priceSubtotal: map{currency: str, value: str}, tax: map{currency: str, value: str}, total: map{currency: str, value: str}}, shippingAddress: map{addressLine1: str, addressLine2: str, city: str, country: str, county: str, phoneNumber: str, postalCode: str, recipient: map{firstName: str, lastName: str}, stateOrProvince: str}, warnings: [map]} # OK
@errors {400: Bad Request, 403: Access Forbidden, 404: Resource Not Found, 409: Conflict, 500: Internal Server Error}

@endpoint POST /guest_checkout_session/{checkoutSessionId}/update_shipping_option
@desc Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.Important! ">Important! (Limited Release) This method is only available to select developers approved by business units.This method changes the shipping method for the specified line item in an eBay guest checkout session. The shipping option can be set for each line item. This gives the shopper the ability choose the cost of shipping for each line item.For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
@required {checkoutSessionId: str # This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.This value is returned by the initiateGuestCheckoutSession method.Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details., Content-Type: str # This header indicates the format of the request body provided by the client. Its value should be set to application/json.  For more information, refer to HTTP request headers.}
@optional {lineItemId: str # A unique eBay-assigned ID value that identifies the line item in a checkout session.For example: v1|2**********6|5**********4 or v1|1**********9|0.For more information about item IDs for RESTful APIs, see Legacy API compatibility, shippingOptionId: str # A unique identifier of the selected shipping option/method.}
@returns(200) {appliedCoupons: [map], checkoutSessionId: str, lineItems: [map], pricingSummary: map{additionalSavings: map{currency: str, value: str}, adjustment: map{amount: map{currency: str, value: str}, label: str}, deliveryCost: map{currency: str, value: str}, fee: map{currency: str, value: str}, importCharges: map{amount: map{currency: str, value: str}, applicableChargeType: str}, importTax: map{amount: map{currency: str, value: str}, importTaxType: str}, priceDiscount: map{currency: str, value: str}, priceSubtotal: map{currency: str, value: str}, tax: map{currency: str, value: str}, total: map{currency: str, value: str}}, shippingAddress: map{addressLine1: str, addressLine2: str, city: str, country: str, county: str, phoneNumber: str, postalCode: str, recipient: map{firstName: str, lastName: str}, stateOrProvince: str}, warnings: [map]} # OK
@errors {400: Bad Request, 403: Access Forbidden, 404: Resource Not Found, 409: Conflict, 500: Internal Server Error}

@endgroup

@group guest_purchase_order
@endpoint GET /guest_purchase_order/{purchaseOrderId}
@desc Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.Important! ">Important! (Limited Release) This method is only available to select developers approved by business units.This method retrieves the details about a specific guest purchase order. It returns the line items, including purchase  order status, dates created and modified, item quantity and listing data, payment and shipping information, and prices, taxes, discounts and credits.The purchaseOrderId is passed in as a URI parameter and is required.Note: The purchaseOrderId value is returned in the call-back URL that is sent through the new eBay pay widget. For more information about eBay managed payments and the new Order API payment flow, see Order API in the Buying Integration Guide.You can use this method to not only get the details of a purchase order, but to check the value of the purchaseOrderPaymentStatus field to determine if the order has been paid for. If the order has been paid for, this field will return PAID.For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
@required {purchaseOrderId: str # This path parameter specifies the unique identifier of a purchase order made by a guest buyer, for which details are to be retrieved.Note: This value is returned in the response URL that is sent through the new eBay pay widget. For more information about eBay managed payments and the new Order API payment flow, see Order API in the Buying Integration Guide.}
@returns(200) {lineItems: [map], pricingSummary: map{additionalSavings: map{currency: str, value: str}, adjustment: map{amount: map{currency: str, value: str}, label: str}, deliveryCost: map{currency: str, value: str}, deliveryDiscount: map{currency: str, value: str}, fee: map{currency: str, value: str}, importCharges: map{currency: str, value: str}, importTax: map{amount: map{currency: str, value: str}, importTaxType: str}, priceDiscount: map{currency: str, value: str}, priceSubtotal: map{currency: str, value: str}, tax: map{currency: str, value: str}, total: map{currency: str, value: str}}, purchaseOrderCreationDate: str, purchaseOrderId: str, purchaseOrderPaymentStatus: str, purchaseOrderStatus: str, refundedAmount: map{currency: str, value: str}, warnings: [map]} # OK
@errors {400: Bad Request, 403: Access Forbidden, 404: Not Found, 500: Internal Server Error}

@endgroup

@end