Loading...
Area: Optimizely B2B Commerce

Billtos API handlers

Recommended reading 

HTTP Verb: POST

URL: /api/v1/billtos

Description: Create a new bill to customer record for the current user

Base: HandlerBase<AddBillToParameter, AddBillToResult>

Handlers:

Order Handler Description
500 AddBillToHandler Add new bill to. If requester is not signed in then handler return error result. If request is not guest and Email parameter is blank or invalid then handler return error result. If Phone parameter is invalid then handler return error result.
Order Handler Description
500 ValidateContext Validates the Email and Phone properties on the parameter object.
600 AddBillTo Inserts a new bill-to Customer into the database using the properties on the parameter object to populate the new entity. The customer is stored in the BillTo property on the result object.
650 AddCostCodes If the CostCodes property on the parameter object contains any cost codes, the application adds new cost codes for the bill-to customer.
700 CopyCustomerPropertiesToEntity Copies custom properties configured for the customer entity to the Customer object stored in the BillTo property on the result object.
800 CreateGetBillToResult Using the CreateGetBillToResult pipeline, the BillTo property on the result object is transformed into a GetBillToResult. The result is stored in the GetBillToResult property on the result object.

HTTP Verb: POST

URL: /api/v1/billtos/{billToId}/shiptos

Description: Create a new ship to customer record for a specific bill to customer record

Base: HandlerBase<AddShipToParameter, AddShipToResult>

Handlers:

Order Handler OrderDescription
500 AddShipToHandler Adds ship to for specific bill to. If requester is not signed in then handler return error result. If BillToId parameter not specified then handler add ship to to current bill to. If current user doesn't have any bill to then handler return error result. If Phone parameter is invalid then handler return error result.
Order Handler OrderDescription
500 ValidateContext Validates the Email and Phone properties on the parameter object.
600 GetBillTo Retrieves a bill-to customer using the GetBillToHandler handler chain. The BillToId property on the parameter object is used to find the bill-to customer. The bill-to customer is stored in the BillTo property on the result object.
700 AddShipTo Inserts a new ship-to Customer into the database using the properties on the parameter object to populate the new entity. Also associates the bill-to customer with the new ship-to customer and assigns the ship-to customer to the current user. The customer is stored in the ShipTo property on the result object.
800 CopyCustomerPropertiesToEntity Copies custom properties configured for the Customer entity to the Customer object stored in the ShipTo property on the result object.
900 CreateGetShipToResult Using the CreateGetShipToResult pipeline, the ShipTo property on the result object is transformed into a GetShipToResult. The result is stored in the GetShipToResult property on the result object.

HTTP Verb: GET

URL: /api/v1/billtos

Description: Return a collection of bill to customer records for the current user

Base: HandlerBase<GetBillToCollectionParameter, GetBillToCollectionResult>

Handlers:

Order Handler Description
500 GetBillToCollectionHandler Gets bill to collection. If requester is not signed in then handler return error result. If current user doesn't have any bill to then handler return error result.
Order Handler Description
500 ValidateContext Validates the current user is authenticated. If the current user is not authenticated, an error is returned.
600 GetSettings Uses the GetCustomerSettingsHandler handler chain to retrieve customer settings and stores them in the GetCustomerSettingsResult property on the result object.
700 GetBillToQuery Creates the initial bill-to customer query that returns available bill-to customers for the current website and user. Other than filtering by current website and user, this query has not been filtered, sorted, or paged. The query is stored in the BillToQuery property on the result object.
800 ApplyExpands Expands the BillToQuery property on the result object by retrieving related objects.
  • If the GetCostCodes property on the parameter object is true, the query will retrieve customer cost codes.
  • If the GetState property on the parameter object is true, the query will retrieve the state for each customer.
  • If the GetCountry property on the parameter object is true, the query will retrieve the country for each customer.
  • If the GetUserProfiles property on the parameter object is true, the query will retrieve users assigned to each customer.
900 ApplyFiltering Applies filtering to the BillToQuery property on the result object. If the BillToId property on the parameter object has a value, the query will be filtered to return only customers with that id. Filters the BillToQuery using the Filter property on the parameter object by searching in the CustomerNumber, ErpNumber, CompanyName, FirstName, LastName, Address1, Address2, City, and PostalCode properties.
1000 ApplySort Applies sorting to the BillToQuery property on the result object. If the Sort property on the parameter object has a value, the query will be sorted with that value. If the Sort property on the parameter object DOES NOT have a value, the query will be sorted by the Customer.CustomerNumber property.
1100 ApplyPaging Applies paging to the BillToQuery. If the PageSize property on the parameter object has a value, the query is paged using the PageSize and Page properties on the parameter object.
1200 ExecuteQuery Executes the BillToQuery after the query has been expanded, filtered, sorted, and paged. The result is stored in the BillToCollection property on the result object.
1300 CreateGetBillToResults If any customers are contained in the BillToCollection property on the result object, they are transformed into a collection of GetBillToResult objects using the CreateGetBillToResult pipeline. The result is stored in the GetBillToResults property on the result object.
1400 GetShipTos If the GetShipTos property on the parameter object is true, the ship-to customers will be retrieved for every bill-to customer in the GetBillToResults property on the result object. The results are stored in each of the GetBillToResult.GetShipToResults properties.
1500 GetValidation If the GetValidation property on the parameter object is true, the customer address form validation will be retrieved. The validation is configured using the Bill To Address Fields configured in the Admin Console. After the validation is retrieved, it is stored in the Validation property of each customer in the GetBillToResults property on the result object.
1600 SetDefaultBillTo If the current user has a default customer, that customer is found in the GetBillToResults property on the result object and the IsDefault property is marked with "true".

HTTP Verb: GET

URL: /api/v1/billtos/{billToId}

Description: Return a single bill to customer record

Base: HandlerBase<GetBillToParameter, GetBillToResult>

Handlers:

Order Handler Description
500 GetBillToHandler Gets bill to. If requester is not signed in then handler return error result. If BillToId parameter not specified then handler return current bill to. If current user doesn't have any bill to then handler return error result. If GetShipTos parameter set to 'true' handler also return ship to collection for returned bill to.
Order Handler Description
500 ValidateContext Validates the BillToId property on the parameter object has a value and the current context has a bill-to customer.
600 GetBillTo Retrieves a bill-to customer using the GetBillToCollectionHandler handler chain. If the BillToId property on the parameter object has a value, that value is used to find the bill-to customer. If the BillToId property on the parameter object DOES NOT have a value, the current bill-to customer in context is used to find the bill-to customer. If a bill-to customer is not found or more than one bill-to customer is found, an error is returned.

HTTP Verb: GET

URL: /api/v1/billtos/{billToId}/shiptos

Description: Return a collection of ship to customer records for a specific bill to customer record

Base: HandlerBase<GetShipToCollectionParameter, GetShipToCollectionResult>

Handlers:

Order Handler Description
500 GetShipToCollectionHandler Gets a collection of ship to customer records for a specific bill to customer record and applies filtering and sorting. If requester is not signed in then handler return error result. If BillToId parameter not specified then handler return ship to collection for current bill to. If current user doesn't have any bill to then handler return error result.
Order Handler Description
500 GetSettings Uses the GetCustomerSettingsHandler handler chain to retrieve customer settings and stores them in the GetCustomerSettingsResult property on the result object.
600 GetBillTo Retrieves a bill-to customer using the GetBillToHandler handler chain. The BillToId property on the parameter object is used to find the bill-to customer. The bill-to customer is stored in the BillTo property on the result object.
700 GetShipToQuery Creates the initial ship-to customer query that returns ship-to customers. If the AssignedOnly property on the parameter object is true, the application retrieves ship-to customers assigned to the bill-to customer and current user (this does NOT include the bill-to customer, even if it's also a ship-to customer). Otherwise, the application retrieves the ship-to customers assigned to the bill-to customer and current user (this does include the bill-to customer). Other than the previous filtering, this query has not been filtered, sorted, or paged. The query is stored in the ShipToQuery property on the result object.
800 ApplyExpands Expands the ShipToQuery property on the result object by retrieving related objects.
  • If the GetState property on the parameter object is true, the query will retrieve the state for each customer.
  • If the GetCountry property on the parameter object equals is true, the query will retrieve the country for each customer.
900 ApplyFiltering Applies filtering to the ShipToQuery property on the result object. If the ShipToId property on the parameter object has a value, the query will be filtered to return only customers with that id. If the ExcludeBillTo property on the parameter object is true, the ShipToQuery will be filtered to exclude the bill-to customer associated with the ship-to customers (the bill-to customer in the BillTo property on the result object). Filters the ShipToQuery using the Filter property on the parameter object by searching in the CustomerNumber, ErpNumber, CompanyName, FirstName, LastName, Address1, Address2, City, and PostalCode properties.
1000 ApplySort Applies sorting to the ShipToQuery property on the result object. If the Sort property on the parameter object has a value, the query will be sorted with that value. If the Sort property on the parameter object DOES NOT have a value, the query will be sorted by the Customer.CustomerSequence property.
1100 ApplyPaging Applies paging to the ShipToQuery. If the PageSize property on the parameter object has a value, the query is paged using the PageSize and Page properties on the parameter object.
1200 ExecuteQuery Executes the ShipToQuery after the query has been expanded, filtered, sorted, and paged. The result is stored in the ShipToCollection property on the result object.
1300 CreateGetShipToResults If any customers are contained in the ShipToCollection property on the result object, they are transformed into a collection of GetShipToResult objects using the CreateGetShipToResult pipeline. The result is stored in the GetShipToResults property on the result object.
If the ExcludeBillTo property on the parameter object is false, the bill-to customer is also transformed into a GetShipToResult and added to the GetShipToResults. This addresses the scenario where the user wants to use the billing address as the shipping address.
If the ExcludeCreateNew property on the parameter object is false, a new empty customer is also transformed into a GetShipToResult and added to the GetShipToResults. This addresses the scenario where the user is allowed to create a new shipping address.
1400 GetValidation If the GetValidation property on the parameter object is true, the customer address form validation will be retrieved. The validation is configured using the Ship To Address Fields configured in the Admin Console. After the validation is retrieved, it is stored in the Validation property of each customer in the GetShipToResults property on the result object.
1500 GetApprovalCounts If the GetApprovalCounts property on the parameter object is true, the application retrieves customer orders for each ship-to customer (and associated bill-to customer) in the GetShipToResults property. The customer orders retrieved meet ALL of the following requirements:
  • Has a status of "AwaitingApproval"
  • The current user has the "Administrator" role OR the current user needs to approve the order OR the current user requested the order be approved
If any orders are found, the total number of orders is stored in the Label property of each of the GetShipToResult objects. The format of the label is:
({total_number_of_orders}) {original_customer_label}
where {original_customer_label} displays the customers company name and address.

HTTP Verb: GET

URL: /api/v1/billtos/{billToId}/shiptos/{shipToId}

Description: Return a single ship to customer record for a specific bill to customer record

Base: HandlerBase<GetShipToParameter, GetShipToResult>

Handlers:

Order Handler

Description

500 GetShipToHandler

Gets specific ship to customer record. If requester is not signed in then handler return error result. If BillToId parameter not specified then handler search ship to in current bill to. If current user doesn't have any bill to then handler return error result. If ShipToId parameter not specified then handler return current ship to. If no ship to with that ShipToId or ship to not in specified bill to then handler return error result.

Order Handler Description
500 ValidateContext Validates the ShipToId property on the parameter object has a value and the current context has a ship-to customer.
600 GetShipTo Retrieves a ship-to customer using the GetShipToCollectionHandler handler chain. If the ShipToId property on the parameter object has a value, that value is used to find the ship-to customer. If the ShipToId property on the parameter object DOES NOT have a value, the current ship-to customer in context is used to find the ship-to customer. If a ship-to customer is not found or more than one ship-to customer is found, an error is returned.

HTTP Verb: PATCH

URL: /api/v1/billtos/{billToId}

Description: Update a single bill to customer record

Base: HandlerBase<UpdateBillToParameter, UpdateBillToResult>

Handlers:

Order Handler

Description

500 UpdateBillToHandler

Updates bill to. If requester is not signed in then handler return error result. If BillToId parameter not specified then handler update current bill to. If current user doesn't have any bill to then handler return error result. If Phone parameter is invalid then handler return error result.

Order Handler Description
500 ValidateContext Validates the Email and Phone properties on the parameter object.
600 GetBillTo Retrieves a bill-to customer using the GetBillToHandler handler chain. The BillToId property on the parameter object is used to find the bill-to customer. The bill-to customer is stored in the BillTo property on the result object.
700 UpdateBillTo Updates the bill-to customer stored in the BillTo property on the result object. Uses properties on the parameter object to update the entity.
800 UpdateCostCodes If the CostCodes property on the parameter object contains any cost codes, the application adds new or updates existing cost codes for the bill-to customer.
900 CopyCustomPropertiesToEntity Copies custom properties configured for the Customer entity to the Customer object stored in the BillTo property on the result object.
1000 CreateGetBillToResult Using the CreateGetBillToResult pipeline, the BillTo property on the result object is transformed into a GetBillToResult. The result is stored in the GetBillToResult property on the result object.

HTTP Verb: PATCH

URL: /api/v1/billtos/{billToId}/shiptos/{shipToId}

Description: Update a single ship to customer record for a specific bill to customer record

Base: HandlerBase<UpdateShipToParameter, UpdateShipToResult>

Handlers:

Order Handler

Description

500 UpdateShipToHandler

Updates user ship to. If requester is not signed in then handler return error result. If BillToId parameter not specified then handler search ship to in current bill to. If current user doesn't have any bill to then handler return error result. If ShipToId parameter not specified then handler update current ship to. If no ship to with that ShipToId or ship to not in specified bill to then handler return error result. If Phone parameter is invalid then handler return error result.

800 UpdateShipToPunchOutHandler

If the current session is a punchout session then handler generates error result.

Order Handler Description
100 ValidatePunchout If the current user has an active PunchOut session, an error is returned. Due to PunchOut business rules, a user in an active PunchOut session cannot change the current ship-to customer.
500 ValidateContext Validates the Email and Phone properties on the parameter object.
600 GetShipTo Retrieves a ship-to customer using the GetShipToHandler handler chain. The BillToId and ShipToId properties on the parameter object are used to find the bill-to and ship-to customers. The bill-to and ship-to customers are stored in the BillTo and ShipTo property on the result object, respectively.
700 UpdateShipTo Updates the ship-to customer stored in the ShipTo property on the result object. Uses properties on the parameter object to update the entity.
800 CopyCustomPropertiesToEntity Copies custom properties configured for the Customer entity to the Customer object stored in the ShipTo property on the result object.
900 CreateGetShipToResult Using the CreateGetShipToResult pipeline, the ShipTo property on the result object is transformed into a GetShipToResult. The result is stored in the GetShipToResult property on the result object.
Do you find this information helpful? Please log in to provide feedback.

Last updated: Dec 11, 2020

Recommended reading