Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Billtos API handler

Describes a bill-to-customer record for the current user.

HTTP Verb – POST

URL – /api/v1/billtos

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

Base – HandlerBase<AddBillToParameter, AddBillToResult>

Handlers –

OrderHandlerDescription
500AddBillToHandlerAdd 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.
OrderHandlerDescription
500ValidateContextValidates the Email and Phone properties on the parameter object.
600AddBillToInserts 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.
650AddCostCodesIf the CostCodes property on the parameter object contains any cost codes, the application adds new cost codes for the bill-to customer.
700CopyCustomerPropertiesToEntityCopies custom properties configured for the customer entity to the Customer object stored in the BillTo property on the result object.
800CreateGetBillToResultUsing 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 –

OrderHandlerOrderDescription
500AddShipToHandlerAdds 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.
OrderHandlerOrderDescription
500ValidateContextValidates the Email and Phone properties on the parameter object.
600GetBillToRetrieves 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.
700AddShipToInserts 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.
800CopyCustomerPropertiesToEntityCopies custom properties configured for the Customer entity to the Customer object stored in the ShipTo property on the result object.
900CreateGetShipToResultUsing 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 –

OrderHandlerDescription
500GetBillToCollectionHandlerGets 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.
OrderHandlerDescription
500ValidateContextValidates the current user is authenticated. If the current user is not authenticated, an error is returned.
600GetSettingsUses the GetCustomerSettingsHandler handler chain to retrieve customer settings and stores them in the GetCustomerSettingsResult property on the result object.
700GetBillToQueryCreates 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.
800ApplyExpandsExpands 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.
900ApplyFilteringApplies 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.
1000ApplySortApplies 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.
1100ApplyPagingApplies 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.
1200ExecuteQueryExecutes the BillToQuery after the query has been expanded, filtered, sorted, and paged. The result is stored in the BillToCollection property on the result object.
1300CreateGetBillToResultsIf 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.
1400GetShipTosIf 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.
1500GetValidationIf 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.
1600SetDefaultBillToIf 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 –

OrderHandlerDescription
500GetBillToHandlerGets 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.
OrderHandlerDescription
500ValidateContextValidates the BillToId property on the parameter object has a value and the current context has a bill-to customer.
600GetBillToRetrieves 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 –

OrderHandlerDescription
500GetShipToCollectionHandlerGets 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.
OrderHandlerDescription
500GetSettingsUses the GetCustomerSettingsHandler handler chain to retrieve customer settings and stores them in the GetCustomerSettingsResult property on the result object.
600GetBillToRetrieves 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.
700GetShipToQueryCreates 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.
800ApplyExpandsExpands 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.
900ApplyFilteringApplies 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.
1000ApplySortApplies 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.
1100ApplyPagingApplies 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.
1200ExecuteQueryExecutes the ShipToQuery after the query has been expanded, filtered, sorted, and paged. The result is stored in the ShipToCollection property on the result object.
1300CreateGetShipToResultsIf 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.
1400GetValidationIf 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.
1500GetApprovalCountsIf 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 –

OrderHandlerDescription
500GetShipToHandlerGets 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.
OrderHandlerDescription
500ValidateContextValidates the ShipToId property on the parameter object has a value and the current context has a ship-to customer.
600GetShipToRetrieves 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 –

OrderHandlerDescription
500UpdateBillToHandlerUpdates 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.
OrderHandlerDescription
500ValidateContextValidates the Email and Phone properties on the parameter object.
600GetBillToRetrieves 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.
700UpdateBillToUpdates the bill-to customer stored in the BillTo property on the result object. Uses properties on the parameter object to update the entity.
800UpdateCostCodesIf 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.
900CopyCustomPropertiesToEntityCopies custom properties configured for the Customer entity to the Customer object stored in the BillTo property on the result object.
1000CreateGetBillToResultUsing 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 –

OrderHandlerDescription
500UpdateShipToHandlerUpdates 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.
800UpdateShipToPunchOutHandlerIf the current session is a punchout session then handler generates error result.
OrderHandlerDescription
100ValidatePunchoutIf 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.
500ValidateContextValidates the Email and Phone properties on the parameter object.
600GetShipToRetrieves 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.
700UpdateShipToUpdates the ship-to customer stored in the ShipTo property on the result object. Uses properties on the parameter object to update the entity.
800CopyCustomPropertiesToEntityCopies custom properties configured for the Customer entity to the Customer object stored in the ShipTo property on the result object.
900CreateGetShipToResultUsing 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.