The SoftLayer API

class: center, middle
# .center[Packages and Invoices]
Christopher Gallo, Senior API Developer

---

# Catalog

---

# Packages
<img src='./img/articles/SL Packages-package-relations.drawio.png' height="500px" class="centerImage"></img>
---

<img src='./img/articles/slcli-order-package-list.png' width="100%" class="centerImage"></img>
---

# Presets

```
$ slcli call-api SoftLayer_Product_Package getAllObjects --mask="mask[id,keyName,activePresetCount]"
 --json-filter='{"activePresets":{"operation":"not null"}}'
┌───────────────────┬──────┬──────────────────────────────────────────────────────────────────┐
│ activePresetCount │  id  │                             keyName                              │
├───────────────────┼──────┼──────────────────────────────────────────────────────────────────┤
│         1         │ 144  │                              3U_GPU                              │
│         6         │ 200  │                        BARE_METAL_SERVER                         │
│        100        │ 835  │                       PUBLIC_CLOUD_SERVER                        │
│         6         │ 865  │                     NETWORK_VLAN_FOR_SERVICE                     │
│         5         │ 885  │                           8U_BI_S2_H4                            │
│        56         │ 991  │                      TRANSIENT_CLOUD_SERVER                      │
│        56         │ 1035 │                       SUSPEND_CLOUD_SERVER                       │
│         9         │ 1045 │                          2U_BI_S3_H2000                          │
│         7         │ 1075 │                   2U_IC4V_FIXED_CONFIGURATIONS                   │
│        32         │ 1109 │                           BI_S4_H2000                            │
│         8         │ 1117 │                           BI_S4_H4000                            │
│         7         │ 1119 │                           BI_S4_H8000                            │
│         5         │ 2636 │                    2U_BI_S4_H2000_AEP_ENABLED                    │
│         5         │ 2676 │                    4U_BI_S4_H4000_AEP_ENABLED                    │
│         5         │ 2700 │                    4U_BI_S4_H8000_AEP_ENABLED                    │
└───────────────────┴──────┴──────────────────────────────────────────────────────────────────┘
```

---

# Items

<img src='./img/articles/slcli-order-item-list1.png' width="100%" class="centerImage"></img>
---

# Items with restrictions

---

# Categories

---

# Required Categories
<img src='./img/articles/slcli-package-getCategories.png' width="90%" class="centerImage"></img>
---

# Prices

```bash
slcli -v  --format=json call-api SoftLayer_Product_Package getItems --id=835 
--mask="mask[id,keyName,prices[id,pricingLocationGroup,locationGroupId,recurringFee,hourlyRecurringFee]]"
```

```json
{
  "id": 13093, "keyName": "RAM_4_VGB",
  "prices": [{ 
      "hourlyRecurringFee": ".04", "recurringFee": "26.55" "id": 223811,
      "locationGroupId": null, "pricingLocationGroup": null,
    }, {
      "hourlyRecurringFee": ".0412", "recurringFee": "27.35" "id": 223813,
      "locationGroupId": 503,
      "pricingLocationGroup": {
        "locations": [
          {"longName": "Amsterdam 1"}, {"longName": "Toronto 1"}, {"longName": "Toronto 3"},
        ]
      }
    }
  ]
}

```

---

#Conflicts

```bash
slcli -v  --format=json call-api SoftLayer_Product_Package  getItemConflicts --id=835 
--mask="mask[item[description,id]]"
```

```json
{
  "item": {
    "description": "Ubuntu Linux 20.04 LTS Focal Fossa Minimal Install (64 bit)",
    "id": 15820
  },
  "itemId": 15820,
  # SoftLayer_Product_Item id this item conflicts with.
  "resourceTableId": 23732   #  VEEAM_AVAILABILITY_SUITE_11A
}
```

---

# Ordering

<pre>
<code class="bash h1js remark-code" >
slcli order place --verify <text style="color:orange">--preset B1_2X8X100</text> --billing hourly \
  --complex-type <text style="color:SlateBlue">SoftLayer_Container_Product_Order_Virtual_Guest</text> \
  --extras '{"virtualGuests": [{"hostname": "test", "domain": "ibm.com"}]}' \
  <text style="color:red">PUBLIC_CLOUD_SERVER</text> \
  <text style="color:violet">DALLAS13</text> \
  <text style="background-color: LightGrey;">BANDWIDTH_0_GB_2</text> \
  OS_UBUNTU_20_04_LTS_FOCAL_FOSSA_MINIMAL_64 \
  <text style="background-color: LightGrey;">MONITORING_HOST_PING</text> \
  NOTIFICATION_EMAIL_AND_TICKET \
  <text style="background-color: LightGrey;">1_IP_ADDRESS 1_IPV6_ADDRESS</text> \
  1_GBPS_PUBLIC_PRIVATE_NETWORK_UPLINKS \
  <text style="background-color: LightGrey;">REBOOT_REMOTE_CONSOLE</text> \
  AUTOMATED_NOTIFICATION \
  <text style="background-color: LightGrey;">UNLIMITED_SSL_VPN_USERS_1_PPTP_VPN_USER_PER_ACCOUNT</text> \
</code></pre>

---

## Find the Datacenter ID

```bash
curl -u $SL_USER:$SL_APIKEY -g \
'https://api.softlayer.com/rest/v3.1/SoftLayer_Location/getDatacenters.json?
objectMask=mask[id,longName,name,regions[keyname,description]]
&resultLimit=0,1
&objectFilter={"regions":+{"keyname":+{"operation":+"DALLAS13"}}}'
```

```json
[
  {
      "id":1854895,
      "longName":"Dallas 13",
      "name":"dal13",
      "regions":[{"description":"DAL13 - Dallas ","keyname":"DALLAS13"}]
  }
]
```

---

## Find the Package ID

```bash
curl -u $SL_USER:$SL_APIKEY -g \
'https://api.softlayer.com/rest/v3.1/SoftLayer_Product_Package/getAllObjects.json? \
objectMask=mask[id] \
&objectFilter={"keyName":+{"operation":+"PUBLIC_CLOUD_SERVER"}}'
```

```json
[{"id":835}]
```

---

## Get the Preset Id

```bash
curl -u $SL_USER:$SL_APIKEY -g \
'https://api.softlayer.com/rest/v3.1/SoftLayer_Product_Package/835/getActivePresets.json?
objectFilter={"activePresets":{"keyName":{"operation":"_=B1_2X8X100"}},
              "accountRestrictedActivePresets":{"keyName":{"operation":"_=B1_2X8X100"}}}'
```

```json
[{
  "description":"B1.2x8x100",
  "id":337,
  "isActive":"1",
  "keyName":"B1_2X8X100",
  "name":"B1.2x8x100",
  "packageId":835
}]
```
---

## Get Package Prices

```bash
curl -u $SL_USER:$SL_APIKEY -g \
'https://api.softlayer.com/rest/v3.1/SoftLayer_Product_Package/835/getItems.json?
objectMask=mask[id,description,capacity,itemCategory,keyName,prices[categories]]'
```

<pre>
<code class="json h1js remark-code" >[{
    "id": 15820,  # Item ID
    "keyName": "OS_UBUNTU_20_04_LTS_FOCAL_FOSSA_MINIMAL_64",
    "prices": [{<text style="background-color: yellow;">"id": 262426</text>, "locationGroupId": null}] # Price Id
  }, {
    "id": 4097,  # Item ID
    "keyName": "1_IPV6_ADDRESS",
    "prices": [{<text style="background-color: yellow;">"id": 17129</text>, "locationGroupId": null}] # Price Id
  }, {
    "id": 188,  # Item ID
    "keyName": "1_GBPS_PUBLIC_PRIVATE_NETWORK_UPLINKS",
    "prices":  [{<text style="background-color: yellow;">"id": 274</text>, "locationGroupId": null}] # Price Id
  },
]
</code></pre>

---

## Place the actual order

```bash
curl -u $SL_USER:$SL_APIKEY -X POST -g  -d 
{"parameters": [
  {"orderContainers": [
    {"virtualGuests": [{"hostname": "test", "domain": "ibm.com"}],
     "packageId": 835,
     "quantity": 1, 
     "location": 1854895, # DALLAS 13
     "useHourlyPricing": true, 
     "presetId": 337,   # B1_2X8X100
     "complexType": "SoftLayer_Container_Product_Order_Virtual_Guest",
     "prices": [
      {"id": 1800}, #  BANDWIDTH_0_GB_2
      {"id": 55},  # MONITORING_HOST_PING
      {"id": 57}, # NOTIFICATION_EMAIL_AND_TICKET
      {"id": 262426},  # OS_UBUNTU_20_04_LTS_FOCAL_FOSSA_MINIMAL_64
      {"id": 21},  # 1_IP_ADDRESS
      {"id": 17129},  # 1_IPV6_ADDRESS
      {"id": 274},  # 1_GBPS_PUBLIC_PRIVATE_NETWORK_UPLINKS
      {"id": 905}, # REBOOT_REMOTE_CONSOLE
      {"id": 58},  # AUTOMATED_NOTIFICATION
      {"id": 420}] # UNLIMITED_SSL_VPN_USERS_1_PPTP_VPN_USER_PER_ACCOUNT
}]}]}
'https://api.softlayer.com/rest/v3.1/SoftLayer_Product_Order/verifyOrder.json'
```
---

# Container

- [SoftLayer_Container_Product_Order_Virtual_Guest](https://sldn.softlayer.com/reference/datatypes/SoftLayer_Container_Product_Order_Virtual_Guest/)
- [SoftLayer_Container_Product_Order_Hardware_Server](https://sldn.softlayer.com/reference/datatypes/SoftLayer_Container_Product_Order_Hardware_Server/)
- [SoftLayer_Container_Product_Order_Network_Vlan](https://sldn.softlayer.com/reference/datatypes/SoftLayer_Container_Product_Order_Network_Vlan/)
- [SoftLayer_Container_Product_Order_Network_Storage_AsAService](https://sldn.softlayer.com/reference/datatypes/SoftLayer_Container_Product_Order_Network_Storage_AsAService/)
- A few others...

---

# User Supplied Data

- SSH keys
- Post provision scripts
- Storage groups
- Hostname / Domain
- Vlans
- User Data / Metadata

---

# Receipt

[SoftLayer_Container_Product_Order](https://sldn.softlayer.com/reference/datatypes/SoftLayer_Container_Product_Order/)

```bash
{
  "orderDate": "2022-11-09T16:35:14-06:00",
  "orderDetails":
  {
      "orderContainers":
      [ ... ], # What you ordered will show up here
  },
  "orderId": 99593918,  # need orderId to find the Invoice Id
  "placedOrder":
  {
      "id": 99593918,
      "orderQuoteId": null,
      "userRecordId": 167758,
      "items":
      [ ... ], # What you ordered will show up here
  }
}
```

---

# Quotes

- Saves an order for easier ordering in the future
- Uses the [SoftLayer_Billing_Order_Quote](https://sldn.softlayer.com/reference/services/SoftLayer_Billing_Order_Quote/) service

---

# Invoices

- [SoftLayer_Billing_Invoice](https://sldn.softlayer.com/reference/services/SoftLayer_Billing_Invoice/)
---

---

# Invoice Types

- NEW: Generated when you place an order
- RECURRING: Monthly invoice
- ONE_TIME_CHARGE: in some rare circumstances these will be generated

---

# Finding Your Order

`"orderId": 99593918`

```bash
slcli -vvv order lookup 99593918
```

```bash
curl -u $SL_USER:$SL_APIKEY -g \
'https://api.softlayer.com/rest/v3.1/SoftLayer_Billing_Order/99593918/getObject.json?
objectMask=mask[
  orderTotalAmount,
  initialInvoice[
    id,
    amount, invoiceTotalAmount,
    invoiceTopLevelItems[
      id, description, hostName, domainName,
      category[name], location[name],
      children[id, category[name], description]
    ]
  ],
  items[description],
  userRecord[displayName,userStatus]]
'
```

---

```bash
{ # SoftLayer_Billing_Order
    "createDate": "2022-11-09T16:35:13-06:00",
    "id": 99593918,  
    "initialInvoice":  # SoftLayer_Billing_Invoice
    {   "id": 88779014,
        "invoiceTopLevelItems": # SoftLayer_Billing_Invoice_Item
        [{
            "categoryCode": "guest_core",
            "description": "2 x 2.0 GHz or higher Cores",
            "domainName": "ibm.com",
            "hostName": "test",
            "id": 2476437518,
            "category":{"name": "Computing Instance"},
            "children":[
              {"description": "8 GB", "id": 2476437520}
              {"description": "Reboot / Remote Console", "id": 2476437522}
              {"description": "1 Gbps Public & Private Network Uplinks", "id": 2476437524}],
            "location":{"name": "dal13"}
        }],
        "invoiceTotalAmount": "0"
    },
    "items": [  #  SoftLayer_Billing_Order_Item
        {"description": "2 x 2.0 GHz or higher Cores", "id": 957060124},
        {"description": "8 GB", "id": 957060126 },
        {"description": "Reboot / Remote Console", "id": 957060128},
        {"description": "1 Gbps Public & Private Network Uplinks", "id": 957060130},
]}
```

---

# Finding Catalog prices for an order

```bash
'https://api.softlayer.com/rest/v3.1/SoftLayer_Billing_Order/99593918/getItems.json?
objectMask=mask[id,categoryCode,description,itemPrice[id,locationGroupId,hourlyRecurringFee],hourlyRecurringFee]'
```

```bash
[
  { # SoftLayer_Billing_Order_Item
    "categoryCode": "guest_core",
    "description": "2 x 2.0 GHz or higher Cores",
    "hourlyRecurringFee": "0",
    "id": 957060124, 
    "itemPrice": {  # SoftLayer_Product_Item_Price
      "hourlyRecurringFee": ".06","id": 234756,"locationGroupId": null}
  },
  { # SoftLayer_Billing_Order_Item
    "categoryCode": "ram",
    "description": "8 GB",
    "hourlyRecurringFee": "0",
    "id": 957060126,
    "itemPrice": { # SoftLayer_Product_Item_Price
      "hourlyRecurringFee": ".036","id": 204181,"locationGroupId": null}
  }
]
```

---

# Recap

.columnA[## Packages
- [SoftLayer_Product_Package](https://sldn.softlayer.com/reference/services/SoftLayer_Product_Package)
- [SoftLayer_Product_Item](https://sldn.softlayer.com/reference/datatypes/SoftLayer_Product_Item/)
- [SoftLayer_Product_Item_Price](https://sldn.softlayer.com/reference/services/SoftLayer_Product_Item_Price/)

## Orders
- [SoftLayer_Product_Order](https://sldn.softlayer.com/reference/services/SoftLayer_Product_Order)
- [SoftLayer_Container_Product_Order](https://sldn.softlayer.com/reference/datatypes/SoftLayer_Container_Product_Order_Virtual_Guest)
- [SoftLayer_Billing_Order_Quote](https://sldn.softlayer.com/reference/services/SoftLayer_Billing_Order_Quote)
]
.columnB[
## Invoices

- [SoftLayer_Billing_Invoice](https://sldn.softlayer.com/reference/services/SoftLayer_Billing_Invoice)
- [SoftLayer_Billing_Invoice_Item](https://sldn.softlayer.com/reference/datatypes/SoftLayer_Billing_Invoice_Item)
- [SoftLayer_Billing_Order](https://sldn.softlayer.com/reference/services/SoftLayer_Billing_Order)
]
---

# .center[The End]