The Orders API allows you to create and manage orders that can include information about products for purchase. Use orders to calculate pricing, apply discounts and taxes, and integrate with the Payments API to accept payments.
Available Methods
The Orders client provides the following methods:
Create - Create a new orderBatchGet - Retrieve multiple orders by IDCalculate - Preview order pricing without creating an orderClone - Duplicate an existing orderSearch - Search for orders with filtersGet - Retrieve a single order by IDUpdate - Update an existing orderPay - Pay for an order using approved payments
Create Order
Creates a new order that can include information about products for purchase and settings to apply to the purchase.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.CreateOrderRequest{
Order: &square.Order{
LocationID: "057P5VYJ4A5X1",
ReferenceID: square.String("my-order-001"),
LineItems: []*square.OrderLineItem{
{
Name: square.String("New York Strip Steak"),
Quantity: "1",
BasePriceMoney: &square.Money{
Amount: square.Int64(1599),
Currency: square.CurrencyUsd.Ptr(),
},
},
},
},
IdempotencyKey: square.String("8193148c-9586-11e6-99f9-28cfe92138cf"),
}
response, err := client.Orders.Create(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Order created: %s\n", response.Order.ID)
}
Parameters
The order to create with line items, taxes, and discounts
A unique string that identifies this CreateOrder request. See Idempotency for more information. Response
Any errors that occurred during the request
Batch Get Orders
Retrieves a set of orders by their IDs. If a given order ID does not exist, the ID is ignored instead of generating an error.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.BatchGetOrdersRequest{
LocationID: square.String("057P5VYJ4A5X1"),
OrderIDs: []string{
"CAISEM82RcpmcFBM0TfOyiHV3es",
"CAISENgvlJ6jLWAzERDzjyHVybY",
},
}
response, err := client.Orders.BatchGet(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Retrieved %d orders\n", len(response.Orders))
}
Parameters
The ID of the location for these orders. This field is optional: omit it to retrieve orders within the scope of the current authorization’s merchant ID.
The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request.
Response
The requested orders. This will omit any requested orders that do not exist.
Any errors that occurred during the request
Calculate Order
Enables applications to preview order pricing without creating an order. Useful for showing customers a price preview before they commit to a purchase.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.CalculateOrderRequest{
Order: &square.Order{
LocationID: "D7AVYMEAPJ3A3",
LineItems: []*square.OrderLineItem{
{
Name: square.String("Item 1"),
Quantity: "1",
BasePriceMoney: &square.Money{
Amount: square.Int64(500),
Currency: square.CurrencyUsd.Ptr(),
},
},
},
Discounts: []*square.OrderLineItemDiscount{
{
Name: square.String("50% Off"),
Percentage: square.String("50"),
Scope: square.OrderLineItemDiscountScopeOrder.Ptr(),
},
},
},
}
response, err := client.Orders.Calculate(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Calculated total: %d\n", response.Order.TotalMoney.Amount)
}
Parameters
The order to be calculated. Expects the entire order, not a sparse update.
Identifies one or more loyalty reward tiers to apply during the order calculation. The discounts defined by the reward tiers are added to the order only to preview the effect of applying the specified rewards.
Response
The calculated version of the order provided in the request
Any errors that occurred during the request
Search Orders
Search all orders for one or more locations. Orders include all sales, returns, and exchanges regardless of how or when they entered the Square ecosystem.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.SearchOrdersRequest{
LocationIDs: []string{
"057P5VYJ4A5X1",
"18YC4JDH91E1H",
},
Query: &square.SearchOrdersQuery{
Filter: &square.SearchOrdersFilter{
StateFilter: &square.SearchOrdersStateFilter{
States: []square.OrderState{
square.OrderStateCompleted,
},
},
DateTimeFilter: &square.SearchOrdersDateTimeFilter{
ClosedAt: &square.TimeRange{
StartAt: square.String("2018-03-03T20:00:00+00:00"),
EndAt: square.String("2019-03-04T21:54:45+00:00"),
},
},
},
Sort: &square.SearchOrdersSort{
SortField: square.SearchOrdersSortFieldClosedAt,
SortOrder: square.SortOrderDesc.Ptr(),
},
},
Limit: square.Int(3),
ReturnEntries: square.Bool(true),
}
response, err := client.Orders.Search(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Found %d orders\n", len(response.Orders))
}
Parameters
The location IDs for the orders to query. All locations must belong to the same merchant. Max: 10 location IDs.
Query
*square.SearchOrdersQuery
Query conditions used to filter or sort the results. Note that when retrieving additional pages using a cursor, you must use the original query.
The maximum number of results to be returned in a single page. Default: 500, Max: 1000
A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query.
A Boolean that controls the format of the search results. If true, SearchOrders returns OrderEntry objects. If false, SearchOrders returns complete order objects. Default: false.
Response
The list of orders that match the query
The pagination cursor to retrieve the next set of results
Any errors that occurred during the request
Get Order
Retrieves an order by ID.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.GetOrdersRequest{
OrderID: "CAISEM82RcpmcFBM0TfOyiHV3es",
}
response, err := client.Orders.Get(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Order: %s\n", response.Order.ID)
}
Parameters
The ID of the order to retrieve
Response
Any errors that occurred during the request
Pay Order
Pay for an order using one or more approved payments or settle an order with a total of 0.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.PayOrderRequest{
OrderID: "CAISENgvlJ6jLWAzERDzjyHVybY",
IdempotencyKey: "c043a359-7ad9-4136-82a9-c3f1d66dcbff",
PaymentIDs: []string{
"EnZdNAlWCmfh6Mt5FMNST1o7taB",
"0LRiVlbXVwe8ozu4KbZxd12mvaB",
},
}
response, err := client.Orders.Pay(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Order paid: %s\n", response.Order.ID)
}
Parameters
The ID of the order being paid
A value you specify that uniquely identifies this request among requests you have sent. See Idempotency for more information. The version of the order being paid. If not supplied, the latest version will be paid.
The IDs of the payments to collect. The payment total must match the order total.
Response
Any errors that occurred during the request
