Billtos API handler

8 min

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//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/

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//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: () where displays the customers company name and address.

HTTP Verb – GET

URL – /api/v1/billtos//shiptos/

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/

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//shiptos/

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.